Python 处理 Word 文档,别再死磕 python-docx 了,试试 Spire.Doc

之前有个需求挺常见：系统每天生成一批 Word 报告，然后自动替换里面的数据、插入图片、转 PDF。

一开始很多人第一反应都是 python-docx。

毕竟它免费，安装简单，网上例子也多。

但真正碰到复杂一点的 Word 文件，就开始难受了。

比如：

• 保留原 Word 样式替换内容；
• 批量替换表格里的字段；
• 插入分页；
• 控制页眉页脚；
• Word 转 PDF；
• 处理带图片、目录、复杂格式的文档。

这时候 python-docx 往往会让你开始和 XML 打交道。

我之前也踩过这个坑。

一个看似简单的“替换报告模板里的几个字段”，最后代码越来越长。

后来换了 Spire.Doc 这类专门处理 Word 文档的库，很多事情反而简单了。

python-docx 最大的问题，不是不能用

先说清楚，python-docx 不是不好。

普通场景完全够。

比如生成一个简单合同：

from docx import Documentdoc = Document()doc.add_heading("用户协议", level=1)doc.add_paragraph("用户姓名：张三\n""签署日期：2026-01-01")doc.save("contract.docx")

这种没问题。

但是企业里面真实的 Word 模板，通常不是这么干净。

很多时候模板长这样：

客户名称：{{customer}}订单编号：{{order_no}}产品列表：| 产品 | 数量 ||----|----|| xxx | xxx |审批人：xxx

然后程序每天生成几百份。

要求：

• 不改变格式；
• 不破坏表格；
• 图片位置保持；
• 最后转 PDF。

这时候 python-docx 就开始麻烦了。

因为 Word 本质上不是一个简单文本文件。

里面有：

• paragraph
• run
• table
• style
• relationship
• xml节点

很多时候你看到的是一句话：

订单编号：{{order_no}}

但是 Word 内部可能拆成：

订单编号：{{order_no}}

你直接 replace 根本找不到。

Spire.Doc 处理 Word，思路不一样

Spire.Doc 更接近操作 Word 文档对象。

比如打开模板：

from spire.doc import Documentdoc = Document()doc.LoadFromFile("template.docx")

然后直接替换：

doc.Replace("{{customer}}","上海某科技有限公司",True,True)doc.Replace("{{order_no}}","NO20260110001",True,True)doc.SaveToFile("result.docx")

这个体验和操作 Word 有点像。

不用关心底层 XML 怎么拆。

批量生成报告，这才是它比较舒服的地方

我比较喜欢的一种场景：

数据库里面查数据。

然后套 Word 模板。

每天生成日报。

比如：

import pymysqlfrom spire.doc import Documentdefbuild_report(order_id):    conn = pymysql.connect(        host="127.0.0.1",        user="report",        password="123456",        database="business"    )    cursor = conn.cursor()    cursor.execute("""        select customer,total_amount,status        from order_record        where id=%s        """,        (order_id,)    )    row = cursor.fetchone()    cursor.close()    conn.close()    doc = Document()    doc.LoadFromFile("order_template.docx")    doc.Replace("{{customer}}",        row[0],True,True    )    doc.Replace("{{amount}}",        str(row[1]),True,True    )    doc.Replace("{{status}}",        row[2],True,True    )    doc.SaveToFile(f"report_{order_id}.docx"    )build_report(10086)

这种代码，业务味比较重。

查数据。

套模板。

输出文件。

整个流程比较顺。

表格处理，也是很多人换库的原因

Word 里面最烦的就是表格。

python-docx 操作表格没问题。

但是复杂表格：

• 合并单元格；
• 保留样式；
• 动态增加行；

处理起来会越来越复杂。

Spire.Doc 可以直接操作表格对象。

例如动态增加数据：

from spire.doc import Documentdoc = Document()doc.LoadFromFile("report_template.docx")table = doc.Sections[0].Tables[0]products = [    ("机械键盘", 3),    ("显示器", 2),    ("鼠标", 5)]for name, count in products:    row = table.AddRow()    row.Cells[0].Paragraphs[0].Text = name    row.Cells[1].Paragraphs[0].Text = str(count)doc.SaveToFile("new_report.docx")

实际项目里面，比如订单明细、巡检报告、财务报表，这种需求非常多。

Word 转 PDF，也是一个高频需求

很多系统最终不会直接给用户 Word。

而是：

生成 Word。

转 PDF。

加水印。

归档。

python-docx 本身没有 PDF 能力。

一般还要搭配 LibreOffice。

比如：

docx | | vLibreOffice | | vpdf

中间多一个环境依赖。

Spire.Doc 可以直接转。

from spire.doc import Document, FileFormatdoc = Document()doc.LoadFromFile("report.docx")doc.SaveToFile("report.pdf",    FileFormat.PDF)

部署服务器时少折腾一个组件。

图片、页眉页脚这些，也更接近业务需求

比如生成设备巡检报告。

里面有：

• 设备照片；
• 检测结果；
• 时间；
• 页码。

这些如果用 python-docx 慢慢拼，也不是不能做。

只是代码会越来越像在维护一个 Word 编辑器。

Spire.Doc 提供了对应对象。

比如添加图片：

from spire.doc import Documentdoc = Document()doc.LoadFromFile("device.docx")paragraph = doc.Sections[0].AddParagraph()picture = paragraph.AppendPicture("device.jpg")picture.Width = 300picture.Height = 200doc.SaveToFile("device_report.docx")

那是不是以后都不用 python-docx？

也不是。

我的习惯：

简单文档：

• 邮件附件；
• 小报告；
• 简单合同；

python-docx 足够。

但是下面这些：

• 企业模板；
• 批量生成 Word；
• Word 转 PDF；
• 复杂格式保留；
• 自动化办公系统；

我会优先考虑 Spire.Doc。

因为时间成本比代码成本更贵。

一个功能，本来半天完成。

结果花两天研究 Word XML，这个账其实不划算。

最后说一句。

Python 处理 Word，很多人一开始关注的是“哪个库免费”。

但到了真实项目里，更多考虑的是：

稳定不稳定。

维护成本高不高。

能不能扛住业务变化。

python-docx 更像一个 Word 文档编辑工具。

而 Spire.Doc 更像一个文档处理组件。

如果你的需求已经不是“生成一个简单 docx”，而是让程序长期批量处理 Word，那换一个更适合的工具，往往比继续补代码舒服很多。