简介：这是一份基于 PySide6 的 Word 转 PDF 桌面应用脚本，面向需要频繁处理文档格式转换的办公人员，也很适合正在学习 Python 图形界面开发的初学者。脚本借助 docx2pdf 库调用 Word 底层的转换能力，利用 PySide6 构建直观的交互界面，使用者可以自行选择需要转换的 Word 文档，再单击按钮即可自动完成转换，并立即在界面中获得结果反馈；整个过程无需手动打开办公软件再另存为 PDF，也无需编写任何复杂命令，操作门槛低、转换效率高。资源包采用 rar 压缩格式，整体包含 1 个独立的 Python 源文件，包体大小约为 1KB；代码虽然简短，却完整覆盖了窗口创建、文件选择、转换执行和结果提示等典型环节，便于阅读、调试和二次开发。目前已有 165 人学习浏览，适合作 PySide6 入门示例，也能直接充当日常文档转换小工具。通过阅读这份代码，可以掌握桌面应用界面控件的组合方式，理解 docx2pdf 的调用逻辑，并能将类似思路迁移到 Excel 转 PDF、批量重命名等更多办公自动化场景中，具备较强的实用与学习价值。 相信不少朋友都被“把一批Word文档转成PDF”这种活儿折磨过。尤其在工作流里，合同、标书、报告要归档，挨个打开Word再另存为PDF，不仅慢，还容易在文件名、排版上出岔子。我之前给单位做文档归档工具时，就用PySide6搭了一个桌面小工具，把Word转PDF做成了“选文件-点按钮-等结果”的批量流程。这篇文章直接把整个实现思路、核心代码、踩过的坑都摊开讲，给打算自己写同类工具的朋友做个参考。
1. 整体思路与方案选型
1.1 为什么桌面工具选择了PySide6
当时我其实犹豫过要不要做成网页版，但考虑到这类工具通常是在本地办公环境里用，文档往往涉及内部内容，不适合往服务器上传。桌面工具就成了最稳妥的选择。
PySide6是Qt官方的Python绑定，相比Tkinter，它的控件更现代，文件拖拽、进度条、多线程信号槽这些都是开箱即用；相比Electron，它的打包体积小得多，启动也快，不需要用户额外装浏览器环境。对内部工具来说，界面做到“能看、好用、不花哨”就够了，PySide6在这个尺度上非常合适。
1.2 转换引擎：win32com、docx2pdf、LibreOffice谁更靠谱
先说结论：在Windows环境下，优先选win32com调用本机Word。这是最传统的COM方案，可靠性最高，因为它直接驱动用户电脑里已经装好的Microsoft Word，排版还原度能做到和手动另存为几乎一模一样。
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| win32com | 排版还原度高、可控制Word实例 | 依赖Windows和Office、COM坑较多 | Windows办公环境、需要批量转换 |
| docx2pdf | 本质是win32com的封装，代码简单 | 封装掩盖了细节，出问题难排查 | 快速脚本、单文件转换 |
| LibreOffice | 跨平台、无需Office | 排版还原可能有偏差、要多装一套软件 | Linux/服务器环境、不允许用Office |
| Aspose等商业库 | 功能强、跨平台 | 收费、License限制 | 企业级产品嵌入 |
很多人一开始会冲着“简单”选docx2pdf，但它内部其实也就是调了Word COM，一旦遇到批量文件转换失败、Word进程残留，你根本不知道它卡在哪一步。用win32com虽然代码多一点，但每一步都在自己掌控下，出问题能直接精准定位。
1.3 程序整体结构
这个工具的逻辑不复杂，核心由三层组成：
- 界面层：PySide6负责文件选择、按钮交互、进度条、日志输出。
- 业务层：做文件路径整理、格式校验、失败重试、结果统计。
- 转换层：win32com启动Word进程，执行打开、另存为、关闭。
关键点在于，界面层和转换层必须用多线程隔开。转换是耗时操作，如果直接跑在界面线程里，窗口会进入“未响应”状态，用户体验很差。所以我用QThread把转换任务丢到后台，通过信号把进度传递给界面更新，后面会有专门的小节讲这部分。
2. 界面搭建：纯代码绘制PySide6窗口
2.1 界面布局与控件设计
我先列一下界面的功能清单，避免边写代码边乱加需求：
- 支持通过按钮或者拖拽添加Word文档。
- 支持批量选择，也能单独移除某项。
- 记录输出目录，默认是“源文件所在目录下的pdf文件夹”。
- 红色进度条、状态日志，让用户知道当前处理到第几个文件。
- 一个“开始转换”按钮，转换过程中禁止重复点击。
布局上我采用的是左侧文件列表、右侧操作区的经典结构。顶部是文件操作按钮，中间是QListWidget列表展示待转换文件，底部是输出目录选择和进度条。代码里用QVBoxLayout和QHBoxLayout嵌套实现，整体不用Designer，直接代码写死，方便后续改动逻辑。
这个界面看起来简陋，但实际用下来非常顺手。我建议不要堆太多功能按钮，工具类软件的核心目标就是缩短操作路径。开始转换后，我用setEnabled(False)把主按钮置灰，同时在日志区域打印当前正在处理的文件名，这样用户心里有底。
2.2 为什么丢掉Designer直接手写
网上搜“pyside6没有designer”能搜出一堆帖子，其实Qt官方是提供Designer的，只不过新版PySide6里它被单独拆出来了，导致很多初学者误以为没有。我之前也用过Designer画界面，后来还是放弃，改成纯代码写界面。
原因有两条：第一，Designer生成的.ui文件在版本升级后偶尔会出现兼容性警告，而纯代码写，只要PySide6还在，代码就不会过时；第二，工具类的界面控件数量有限，布局嵌套又简单，纯代码一目了然，不需要额外打开一个GUI工具来回切换。如果你只是做小型内部工具，手写布局反而更快。
2.3 用QThread避免界面卡死
转换一批文档，每份可能耗时几秒到十几秒。在PySide6里如果直接在槽函数里跑循环，QTimer会停摆，事件循环无法处理重绘和鼠标消息，窗口就会被系统判定为“未响应”。
解决办法是建立工作线程。我定义了一个ConvertWorker类，继承QThread，在run()方法里执行整个批量转换流程。用自定义信号progressChanged(int, str)把当前索引、文件名传回主线程，再连接一个槽函数更新进度条和日志。
我遇到的第一个坑就在这里：win32com创建Word实例必须在工作线程里完成，不能在主线程里先创建再传到子线程。Word的COM模型对线程亲和性有要求，换线程后对象可能失效，会抛出“拒绝访问”之类的COM错误。所以我会在run()方法内部完成DispatchEx、循环转换、Quit整个生命周期。
3. 核心转换逻辑与Word进程管理
3.1 转换前置条件
先说环境要求，免得大家装完跑不起来。这个工具只能在Windows上跑，并且本机必须装了Microsoft Office Word，WPS不行。Python版本建议3.8以上，PySide6和pywin32两个依赖缺一不可：
pip install PySide6 pywin32安装pywin32后，有时候需要到Python安装目录下跑一次pywin32_postinstall脚本，否则某些COM接口注册不上。这个问题在新版本里一般不常见，但如果你遇到“接口未注册”之类的报错，优先检查这一步。
3.2 单文件转换核心代码
先写一个最核心的转换函数，单独转换一个Word文件为PDF，不掺界面逻辑，方便验证：
import os import win32com.client WD_FORMAT_PDF = 17 def word_to_pdf(word_app, src_path, dst_path): doc = None try: abs_src = os.path.abspath(src_path) abs_dst = os.path.abspath(dst_path) doc = word_app.Documents.Open(abs_src, ReadOnly=True) doc.SaveAs(abs_dst, FileFormat=WD_FORMAT_PDF) except Exception as e: raise RuntimeError(f"转换失败: {src_path} -> {e}") finally: if doc is not None: doc.Close(SaveChanges=False) if __name__ == "__main__": word_app = win32com.client.DispatchEx("Word.Application") word_app.Visible = False word_app.DisplayAlerts = 0 try: word_to_pdf(word_app, "test.docx", "test.pdf") finally: word_app.Quit()这里有几个关键点要解释清楚。WD_FORMAT_PDF的值是17，这是Word的WdSaveFormat枚举中PDF格式的固定值。打开文档时我加了ReadOnly=True，防止原文档被意外修改。SaveAs时第二个参数就是文件格式，传17表示输出PDF。
每次转换完，在finally里调用doc.Close(SaveChanges=False)。如果某次转换因为文档被占用或加密等原因抛异常，至少要确保文档对象被关闭，否则Word进程内部会悬挂一个隐藏文档，时间一长内存占用居高不下。
3.3 异常处理与系统资源释放
用win32com最让人头疼的就是进程残留。也许你手动跑脚本没问题，但批量转换几十个文件后，任务管理器里能看到好几个WINWORD.EXE像幽灵一样挂着，CPU占用还不低。我排查后发现原因主要有两个：
- 某个文档打开失败，doc.Close没执行，Word实例一直等在那里。
- 调用了word_app.Quit()，但还有Python引用没释放，进程迟迟退不了。
我的处理方式是在外层用try/except/finally把Quit包起来，然后在finally里加一行gc.collect()，强制清理COM包装对象。这里不推荐用“杀进程大法”，因为用户可能正开着别的Word文档，贸然taskkill会把用户数据也带走。
另外要区分Dispatch和DispatchEx的区别。Dispatch会连接系统中已经运行的Word实例，如果用户正在编辑文档，这个操作会干扰到人家；DispatchEx是创建独立的新实例，互不干扰。做工具类软件必须用DispatchEx。
3.4 批量转换与文件重命名策略
批量转换时，除了逐个调用转换函数，还要考虑输出文件重名。比如同一个目录下有“合同V1.docx”和“合同V1.doc”，生成的PDF都叫“合同V1.pdf”，第二个就会覆盖第一个。
我的处理策略很简单——输出目录统一放到源文件同级的pdf_output目录，文件名如果撞车，就在末尾加“_1”“_2”。为了避免Python字符串拼接的麻烦，我用了os.path.splitext拆后缀，再拼上.pdf。路径处理一律用os.path模块，不要手动拼反斜杠，否则在路径包含中文或空格时很容易出问题。
批量转换的代码骨架是下面这样，进度信号每隔一个文件就发一次，日志里记录成功数和失败数：
class ConvertWorker(QThread): progressChanged = Signal(int, int, str) finishedAll = Signal(int, int) def __init__(self, files, out_dir, parent=None): super().__init__(parent) self.files = files self.out_dir = out_dir def run(self): success, failed = 0, 0 word_app = win32com.client.DispatchEx("Word.Application") word_app.Visible = False word_app.DisplayAlerts = 0 try: for idx, src_path in enumerate(self.files): try: dst_path = self.generate_unique_pdf_path(src_path) word_to_pdf(word_app, src_path, dst_path) success += 1 self.progressChanged.emit(idx + 1, len(self.files), os.path.basename(src_path)) except Exception as e: failed += 1 self.progressChanged.emit(idx + 1, len(self.files), f"失败: {os.path.basename(src_path)} - {e}") finally: word_app.Quit() gc.collect() self.finishedAll.emit(success, failed)4. 实操踩坑实录与排查思路
4.1 转换过程中卡住，提示“Word未响应”
网上搜热词“word转pdf office提示未响应”，属于这个工具最常见的故障。我总结下来，卡住的原因通常是文件损坏或包含复杂内容，Word打开时弹了什么隐藏对话框，而我们把Visible设为False之后，对话框出不来，COM调用就一直阻塞。
我的处理办法是双重保险。第一，设置DisplayAlerts=0，让危险提示不再弹窗；第二，把Visible改成True，虽然转换过程中会闪一下窗口，但很多隐藏对话框的问题会直接消失。实测下来，对某些分节符复杂、域代码多的旧文档，Visible=True反而更稳定。
如果还是卡死，就在业务层加超时保护。最简单的做法是把转换任务再包一层线程，超时后放弃当前文件，继续下一个。这是保底策略，避免单份坏文档拖死整批任务。
4.2 PDF输出后排版和Word里看到的不一样
关于“Word转PDF排版错乱”，要区分两种情况：一种是真错乱，分页、字体分布和预览不一致；另一种是心理错乱，PDF和Word的显示方式天然不同，看起来有差异。
如果是第一种，大概率是字体缺失或页面设置有兼容性问题。工具这边能做的就是不要动文档的任何设置，原样打开、原样另存。不要用Normal模板去套，不要修改纸张大小。如果你在Open时不指定参数，Word会套用户的默认模板，有些单位电脑的Normal模板是改过的，转出来的PDF就会很怪。我建议Open时显式传入参数AddToRecentFiles=False，避免它碰用户的近期文件列表。
4.3 Word进程堆积，清理不掉
进程残留问题，原因我在前面的资源释放部分已经讲过。这里再补充一个细节：如果用户电脑上装了WPS，并且把.doc/.docx的默认打开方式劫持成了WPS，那DispatchEx("Word.Application")不一定报错，但某些老版本WPS对COM的支持并不完整，转换可能失败，甚至在Quit之后还残留WPS进程。
解决办法是在启动时检测Word是否真的可调用，如果识别到默认打开方式被第三方接管，就提示用户先安装或修复Office COM组件。这个检测代码不复杂，用win32api的FindExecutable查一下扩展名关联的exe路径即可。
4.4 PyInstaller打包发布的隐藏坑
工具写完，最后要打包成exe给同事用。PyInstaller打包PySide6程序本身就容易踩坑，再叠加win32com，问题就更多了。我的打包命令如下：
pyinstaller -F -w --hide-console minimize-extra --name WordToPDF main.py-F是单文件模式，-w是不显示控制台窗口。PySide6的插件机制有时候会导致打包后找不到平台插件，需要在命令行里加--collect-all PySide6。pywin32也有类似问题，情况严重时需要在spec文件的hiddenimports里手动加win32com相关模块。
还有一个血泪教训：杀毒软件经常把PyInstaller打包出来的单文件exe当病毒处理。这本质上是单文件模式运行时需要在临时目录释放资源，行为特征太像病毒了。后来我把发布包改成了解压版，也就是不带-F的目录模式，误报率明显下降。给同事的压缩包里放一个解压后运行WordToPDF.exe的说明就行。
5. 常见问题速查与个人实测心得
5.1 高频问题速查表
我最后把前后遇到的高频问题整成一张表，方便你快速对症下药：
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
| 导入win32com报错 | 没装pywin32 | pip install pywin32，重开后测试 |
| DispatchEx创建实例失败 | Office未安装或WPS劫持关联 | 安装完整版Office，检查默认打开方式 |
| 转出PDF为空文件 | 原文档加密或权限限制 | 取消文档保护，手动另存验证 |
| 转换卡死、提示未响应 | 文档复杂导致隐藏弹窗 | DisplayAlerts设为0，Visible改为True |
| 批量转换后Word进程多 | COM对象未被释放 | 用DispatchEx，finally里Quit并gc.collect() |
| 打包后exe无法启动 | PySide6插件缺失 | PyInstaller加--collect-all PySide6 |
| 文件名变成乱码 | 路径或编码问题 | 用os.path处理路径，避免手动拼接 |
5.2 实测数据与性能感受
我自己用这套工具批量转过120份Word文档，绝大多数是几十页的合同扫描件和标书文件，机器配置也不高，i5+16GB内存的办公本。整体跑下来大概7分钟，平均一份3到4秒，这个速度完全够日常使用。
不过有个规律要提醒你：前几十份转得很快，到了后面会慢慢变慢。我怀疑是Word实例内部缓存了太多“最近使用”的东西。后来我改成每转换30份就自动重启一次Word实例，整体效率反而更高。
最后再分享一个实用小技巧：转换完成后，我用PyMuPDF（fitz）读取生成的PDF文件，尝试获取总页数，如果连第一页都解析不出来，就判定这次转换产生的PDF损坏，自动重新转换一次。这个校验步骤帮我在那120份文档里揪出了3份隐藏的失败文件，而它们在日志里其实显示的是“成功”。
这类工具说到底是围绕“Word文档生命周期管理”的一环。把转PDF这步做成自动化，后面接PDF合并、加页码、OCR识别，都会顺很多。你可以先跑通这套核心转换流程，再按自己的实际场景往里面加功能。
本文还有配套的精品资源，点击获取
