Flask开发DOCX转PDF转换程序运行报错如何排查修复

核心报错原因 #

你遇到的是docx2pdf库调用COM组件失败的错误，这个库本身不具备独立解析DOCX的能力，Windows环境下完全依赖本地安装的桌面版Microsoft Word完成格式转换，以下是你代码里的所有问题点：

• 未配置有效上传/输出目录：UPLOADER_FOLDER设为空字符串，文件读写全部用相对路径，Flask运行时工作目录偏移就会出现文件找不到、转换失败的问题
• 转换输出文件名逻辑冲突：调用convert()时写死输出文件为hello.pdf，后续又按「上传文件名+.pdf」的规则查找生成的PDF，路径完全不匹配
• 转换函数定义位置错误：把docx2pdf函数写在路由的POST判断分支内，每次请求重复定义函数，容易触发作用域异常
• 未做文件名校验：直接使用用户上传的原始文件名读写文件，特殊字符、空格、路径遍历字符都会引发错误
• 缺少前置依赖校验：如果运行环境没装桌面版Word、Word首次启动的欢迎弹窗没关闭、程序用和Word安装身份不一致的权限运行（比如Word装在普通用户账号，你用管理员权限跑Flask），都会直接触发COM调用报错

修复步骤 #

1. 前置环境准备：
   • 确保运行程序的Windows设备安装了桌面版Microsoft Word（2013及以上版本，WPS兼容性差不推荐）
   • 手动打开一次Word，关闭所有首次启动引导、激活提示弹窗，确保Word可以无弹窗直接进入空白文档界面
   • 在项目根目录新建uploads、outputs两个文件夹，分别存放上传的源文件、转换后的PDF
2. 替换原有代码为修复后的版本：

from flask import Flask
from flask import request, render_template, send_file
import os
from typing import Tuple
from docx2pdf import convert
from werkzeug.utils import secure_filename

# 基于当前脚本位置配置绝对路径，避免工作目录偏移问题
BASE_DIR = os.path.abspath(os.path.dirname(__file__))
UPLOAD_FOLDER = os.path.join(BASE_DIR, 'uploads')
OUTPUT_FOLDER = os.path.join(BASE_DIR, 'outputs')
# 自动创建目录
os.makedirs(UPLOAD_FOLDER, exist_ok=True)
os.makedirs(OUTPUT_FOLDER, exist_ok=True)

app = Flask(__name__)
app.config['UPLOAD_FOLDER'] = UPLOAD_FOLDER
app.config['OUTPUT_FOLDER'] = OUTPUT_FOLDER
# 限制允许上传的文件格式
ALLOWED_EXTENSIONS = {'docx'}

def allowed_file(filename):
    return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS

# 把转换函数移到全局作用域
def docx_convert(input_file: str, output_file: str, pages: Tuple = None):
    if pages:
        pages = [int(i) for i in list(pages) if i.isnumeric()]
    convert(docx_file=input_file, pdf_file=output_file, pages=pages)
    return output_file

@app.route('/', methods=['GET', 'POST'])
def index():
    if request.method == "POST":
        file = request.files.get('filename')
        # 校验文件是否存在、格式是否合法
        if not file or file.filename == '' or not allowed_file(file.filename):
            return "请上传合法的DOCX文件", 400
        # 清洗文件名，避免特殊字符引发错误
        safe_filename = secure_filename(file.filename)
        # 拼接上传文件的绝对路径
        input_path = os.path.join(app.config['UPLOAD_FOLDER'], safe_filename)
        file.save(input_path)
        # 生成对应PDF的输出绝对路径
        pdf_filename = f"{os.path.splitext(safe_filename)[0]}.pdf"
        output_path = os.path.join(app.config['OUTPUT_FOLDER'], pdf_filename)
        # 执行转换
        docx_convert(input_path, output_path)
        # 转换完成直接返回下载，不需要额外做空格替换的传参逻辑
        return send_file(output_path, as_attachment=True, download_name=pdf_filename)
    return render_template("index.html")

if __name__=="__main__":
    app.debug = True
    # 不要用管理员权限运行程序，避免COM组件权限不匹配
    app.run()

额外注意事项 #

• 不要把这个程序直接部署到无GUI的Linux服务器上，docx2pdf在Linux下没有原生支持，就算装LibreOffice兼容性也很差，生产环境建议用专门的文档转换服务
• 如果还是报COM错误，可以打开组件服务：找到组件服务->计算机->我的电脑->DCOM配置->Microsoft Word 97-2003 文档，右键属性给当前运行用户加本地激活、本地启动权限
• 调试的时候不要开多个Flask进程，避免多个进程同时调用Word COM组件引发冲突

内容的提问来源于stack exchange，提问作者Mixhalo