ARTICLE · 1367587
我用Python批量生成Word中文文档踩过的四个坑
我用Python批量生成Word中文文档踩过的四个坑
先说个场景,做内容的人大概都熟。
文章写完要留档,给合作方的说明要出文档,每周的固定汇报要交 Word。这些文档格式都定死了,变的只是里面的标题、数字和几句话。手动弄一份两份还行,一周弄五六份,光复制粘贴改格式就能耗掉半天。
我一直在找不用打开 Word 就能出文档的办法。这周试了 python-docx,GitHub 上的开源库,MIT 许可,pip 一行装好,全程在本机跑,不联网、不登录、不填 key、不花一分钱。我把中文、表格、插图都写进去实测了一遍,好的坏的记在这里。这期的主角就是它。

它到底能干什么
一句话讲,它让代码能写 Word 文档。
你平时在 Word 里点鼠标做的事,打字、设标题、加粗、插表格、放图片,它都能用几行代码做出来。你不用碰界面,跑一遍脚本,一份 docx 就生成好了。
我做个能说明问题的测试。做一份中文文档,带一个大标题、两段正文、一个二行二列的表格。从新建到存盘,实测 0.097 秒,文件 36.2KB。存完我再把它读回来,标题、正文、表格全在,一处不差,读回花了 0.037 秒。整个过程都在本机 CPU 上,一次网都没联。
这类能力放到日常里,能省不少事。你手上有批量数据,想每周自动出一份格式固定的周报,它能写。你给客户出说明文档,把变量填进模板,它能一份份生成。做内容的更用得上:文章写完自动留一份排好版的 Word 备份,不用手动复制。你也可以把它接在自己流程的尾巴上,前面算完的东西,后面自动写成文档。以前这些活要么靠手,要么靠在线办公,现在本机就能办。
装它要付出什么
我在 Windows 10 上建了个全新的 Python 3.10 环境,命令就一行:pip install python-docx。实测 10.49 秒装完,拉进来 3 个包,净增体积 11.1MB,全落在 F 盘,C 盘一个字节没写。装的是 1.2.0 版。
这里我得说句实在话。它只带进来 lxml 和 typing-extensions 两个依赖,加上它自己一共 5 个包、28.5MB。这个体积很轻,硬盘再紧也装得下。这跟那些动不动几百兆的库不一样,你不用为装它腾地方。
还有一点我挺看重。它不用装 Office,不用登录账号,没有额度条,没有要填的 key。代码跑一遍,文档就在那儿了。我愿意写它,就是冲着这个:装上就能用,不跟任何服务绑在一起。

真踩过的四个坑
下面这几条,都是我在本机一次一次撞出来的,不是抄文档猜的。
1、中文设了字体也不生效。我写 run.font.name 等于微软雅黑,以为中文就跟着变了,结果用 Word 打开还是老样子。我去翻了 XML 才弄明白,这一行只写了西文字体那个槽,管中文的 eastAsia 槽还空着。正解是手动补一句 set,把 w:eastAsia 也设成微软雅黑。我实测过,补之前那个槽读出来是空的,补之后才变成微软雅黑。写中文文档,这一句省不得。
2、插图不设宽直接溢出页面。我拿一张 1024 像素的图,没加 width 就往里插。代码算出来它宽 14.22 英寸,可 A4 去掉页边距,可用宽度才 6 英寸,超出去 8.22 英寸。文档一打开,图直接飞到页外面去了。给 add_picture 传一个 width 等于 Inches(6),图片就待在页里了。这个坑不报错,看代码也没毛病,只有打开文档你才发现。
3、表格列宽设了跟没设一样。我给三列分别设成 1、2、3 英寸,网格确实变了,可每个格子的宽度还停在 2880,也就是 2 英寸。Word 渲染表格看的是格子宽度,不看网格宽度,结果还是老老实实三等分。正解是先把 autofit 关掉,再逐格给 c.width 设宽。我设完读出来是 1440、2880、4320,这才对。
4、老 .doc 直接读不了。我喂了个 .doc 进去,它抛 PackageNotFoundError 给我。它只认 .docx,因为 docx 的本质是个 zip 包,老 .doc 是另一种二进制格式。手上要是有老文件,得先用 Office 另存成 .docx 再交给它。这条得提前知道,不然拿到报错你摸不着头脑。

怎么用才顺手
记三件事就够了:中文补 eastAsia,图片给 width,表格逐格设宽。这三条做到,生成的文档打开就规整。
代码不长。导入 Document,建一个文档,add_heading 写标题,add_paragraph 写正文,run 想加粗就设 font.bold。表格用 add_table,记得把 autofit 设成 False。图片用 add_picture,把 width 写上。存的时候一句 save 就出来了。
我还会顺手给文档填一下标题属性,就是 core_properties 里的 title。你生成一百份文档丢在一个文件夹里,光看文件名分不清谁是谁,Word 的详情里要是有标题,找起来快得多。这一行不写也能用,属于用久了自然会加上的东西。
写完我习惯再读一遍。用 Document 把存好的文件重新打开,遍历段落,把有字的段挑出来,再数一下表格几行几列。我那份测试文档读回来,非空段落两段,表格二行二列,跟写进去的一致。这一步花不了几十毫秒,却能在批量出文档之前发现排版跑偏。我吃过亏,有一回中文没补 eastAsia,生成时一切正常,打开才傻眼,加了这道读回校验,同类问题当场就现形。
中文那处我想多说一句。add_heading 生成的标题,默认字体是 Calibri,中文会回退成别的。我给标题里每个 run 都补了 eastAsia,中文才真正用上微软雅黑。正文段落里的中文也一样,只要你在意字体,就得补这一句。嫌一遍遍写麻烦,可以自己封一个小函数,以后每次设字体都走它,省得漏。
表格那边,千万别偷懒只设列宽。我一开始以为 column.width 就够了,实测才发现格子宽度没动,Word 就是三等分。把 autofit 关掉、逐格设宽之后,才按你的意思排。这一点跟很多人想的不一样,我把它记牢了。
图片那处也一样,别指望它按页宽自动缩。你不给 width,它就按图片原始像素算,1024 像素直接变 14.22 英寸。我现在的习惯是每张图都显式写宽度,写死 6 英寸,图大了小了都不会跑偏。

谁该装,谁别碰
该装的,是这几类人。你要批量生成周报、清单、合同这类格式固定的文档。你要把脚本算出来的结果自动写成带表格的 Word。你做内容,想给每篇文章自动留一份排好版的备份。你只想本地免费出 docx,不碰在线办公那一套。
别碰的,也是几类。你要处理老 .doc 或者 WPS 的私有格式,它只认 .docx。你想要精确分页、复杂页眉页脚,那些得自己手写 OOXML,为这点需求不值当。你嫌设字体、设列宽麻烦,只想写一句话就出完美排版,那它不适合你。你想让它认图片里的字,那是 OCR 的活,得另找工具。
说到底,它的价值就一句话:格式固定的 Word,它能帮你批量生成,把手工排版的时间省下来。你前面要裁图,可以用前几期讲过的 Pillow;往后要转成 PDF 发出去,可以配上 fpdf2。一个裁图、一个出 Word、一个出 PDF,本地文档这条线在我这儿就齐了。
我这几期都在做同一件事:一次只拆一个仓库,讲清它能干什么、怎么装、坑在哪、谁适合。挑的都是真正在本机跑通、不联网不花钱的东西。你跟着一期期看下来,手里就攒下一套能自己搭的本地工具箱。
想接着看下一个的,关注「弋然小记」,或者在后台留言扣个 1,我就接着往下挖。















































































