简介这是一份基于 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/服务器环境、不允许用OfficeAspose等商业库功能强、跨平台收费、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 WordWPS不行。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, ReadOnlyTrue) doc.SaveAs(abs_dst, FileFormatWD_FORMAT_PDF) except Exception as e: raise RuntimeError(f转换失败: {src_path} - {e}) finally: if doc is not None: doc.Close(SaveChangesFalse) 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格式的固定值。打开文档时我加了ReadOnlyTrue防止原文档被意外修改。SaveAs时第二个参数就是文件格式传17表示输出PDF。每次转换完在finally里调用doc.Close(SaveChangesFalse)。如果某次转换因为文档被占用或加密等原因抛异常至少要确保文档对象被关闭否则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, parentNone): 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调用就一直阻塞。我的处理办法是双重保险。第一设置DisplayAlerts0让危险提示不再弹窗第二把Visible改成True虽然转换过程中会闪一下窗口但很多隐藏对话框的问题会直接消失。实测下来对某些分节符复杂、域代码多的旧文档VisibleTrue反而更稳定。如果还是卡死就在业务层加超时保护。最简单的做法是把转换任务再包一层线程超时后放弃当前文件继续下一个。这是保底策略避免单份坏文档拖死整批任务。4.2 PDF输出后排版和Word里看到的不一样关于“Word转PDF排版错乱”要区分两种情况一种是真错乱分页、字体分布和预览不一致另一种是心理错乱PDF和Word的显示方式天然不同看起来有差异。如果是第一种大概率是字体缺失或页面设置有兼容性问题。工具这边能做的就是不要动文档的任何设置原样打开、原样另存。不要用Normal模板去套不要修改纸张大小。如果你在Open时不指定参数Word会套用户的默认模板有些单位电脑的Normal模板是改过的转出来的PDF就会很怪。我建议Open时显式传入参数AddToRecentFilesFalse避免它碰用户的近期文件列表。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报错没装pywin32pip install pywin32重开后测试DispatchEx创建实例失败Office未安装或WPS劫持关联安装完整版Office检查默认打开方式转出PDF为空文件原文档加密或权限限制取消文档保护手动另存验证转换卡死、提示未响应文档复杂导致隐藏弹窗DisplayAlerts设为0Visible改为True批量转换后Word进程多COM对象未被释放用DispatchExfinally里Quit并gc.collect()打包后exe无法启动PySide6插件缺失PyInstaller加--collect-all PySide6文件名变成乱码路径或编码问题用os.path处理路径避免手动拼接5.2 实测数据与性能感受我自己用这套工具批量转过120份Word文档绝大多数是几十页的合同扫描件和标书文件机器配置也不高i516GB内存的办公本。整体跑下来大概7分钟平均一份3到4秒这个速度完全够日常使用。不过有个规律要提醒你前几十份转得很快到了后面会慢慢变慢。我怀疑是Word实例内部缓存了太多“最近使用”的东西。后来我改成每转换30份就自动重启一次Word实例整体效率反而更高。最后再分享一个实用小技巧转换完成后我用PyMuPDFfitz读取生成的PDF文件尝试获取总页数如果连第一页都解析不出来就判定这次转换产生的PDF损坏自动重新转换一次。这个校验步骤帮我在那120份文档里揪出了3份隐藏的失败文件而它们在日志里其实显示的是“成功”。这类工具说到底是围绕“Word文档生命周期管理”的一环。把转PDF这步做成自动化后面接PDF合并、加页码、OCR识别都会顺很多。你可以先跑通这套核心转换流程再按自己的实际场景往里面加功能。本文还有配套的精品资源点击获取