Word文档处理大概是办公自动化和日常开发需求里最常碰到的一类任务。从批量生成合同、导出实验报告，到整理会议纪要、做数据报表汇总，需求量一直不小。如果你平时主要用Python做数据处理或脚本落地，又不想在Windows上额外装Office全家桶，那python-docx应该是当前生态里最合适的选择之一。它会直接操作docx文件内部的XML结构，不依赖本机安装Word软件，跨平台可用，写起来也足够简单。

这篇内容我会从头到尾梳理python-docx的核心用法，包括文档读写、样式控制、表格图片插入、页面设置、批量生成实战，以及我实际踩过的坑和排查思路。文章里的代码都是可以直接复制使用的，你只要把路径和字段换成自己的数据就能跑起来。

1. 为什么选择python-docx：定位、能力边界与选型思路

1.1 它到底能做什么

先给不了解的人说明一下。.docx文件和2003时代的老.doc格式不一样，它本质上是一个压缩包，里面是一堆XML文档和资源文件。python-docx做的事情，就是把这堆XML操作封装成Python对象，让你可以像操作对象属性一样去读写Word内容。

基于这个机制，它能实现的功能大致是：

• 创建新文档、打开和修改已有文档
• 添加和编辑段落、文字、标题
• 设置字符格式（字体、大小、加粗、颜色、下划线等）
• 设置段落格式（对齐、缩进、行距、段间距）
• 创建和操作表格，合并单元格，设置单元格内容
• 插入本地图片，控制图片大小
• 设置页面尺寸、页边距、页眉页脚
• 批量生成大量结构相似的文档

它不太适合做的事情也有必要说清楚，免得你走弯路。第一，它不支持老式的.doc格式，遇到.doc文件需要先用工具转成.docx。第二，它不具备文档渲染能力，也就是说不能直接用它把Word转成PDF或图片。第三，不能执行Word宏，不能操作.docm宏文件里的VBA逻辑。第四，无法处理加密文档。

1.2 与其他方案对比：为什么多数场景选它

业内处理Word的方案其实不少，我用实际经验帮你对比一下。

• win32com（pywin32）：通过Windows COM接口调用本机安装的Word软件，功能最强，几乎所有Word能力都能操控。但缺点明显，必须跑在Windows且装了Microsoft Office的机器上，而且实例经常释放不干净，会有僵尸进程卡在那。我只在必须调用Word特有功能（比如另存为其他格式）时才会用它。
• 直接改docx底层XML：用zipfile解包docx，改里面document.xml。这样做上限极高，能实现python-docx做不到的精细控制，但开发和调试成本也高，普通人很难接受。
• docxtpl：基于python-docx之上做的模板引擎，可以在模板里写{{xxx}}占位符，批量填充数据。生成合同、通知这类固定版式的场景非常舒服，但它本质是调python-docx，所以你的python-docx基础越好，用它就越顺手。
• pandoc：主要用于文档格式转换，生成Word版式时可以用，但涉及复杂页眉页脚、动态域时，以及精确控制字节级样式时不如python-docx灵活。

综合来看，如果不是极端复杂版式，python-docx是学习和性价比最高的选择。它API设计得对新手很友好，同时也不限制进阶用户发挥。

1.3 安装与最小验证

安装这个库非常简单，直接用pip就行。

pip install python-docx

装完之后可以跑一段代码验证一下版本，顺便确认环境没问题：

import docx print(docx.__version__)

我之前在装的时候没遇到什么坑，不过有两个小提醒。如果你用的是虚拟环境，记得先激活再装，不然很容易装到全局环境里，后面import报错也不知道错在哪。另外，python-docx依赖lxml库，如果你网络来源安装经常超时，可以换一个源，或者先装lxml再装python-docx。装好后建议新建一个临时目录跑通下面的基础案例，再进入正式项目，这样能减少环境因素带来的干扰。

2. 读写基础：从打开文档到定位内容

2.1 文件的打开、保存与另存

python-docx打开文件的方式有三种，分别对应不同的使用场景。

第一种是创建一个全新的空白文档，适合从零开始生成内容的场景：

from docx import Document doc = Document() doc.save("new_document.docx")

第二种是打开磁盘上已有的docx文件，适合在模板基础上修改，或者读取已有内容：

doc = Document("template.docx")

第三种是通过文件流读取，比如你从对象存储下载、从数据库blob字段拿出来的文档，不需要落到磁盘就能直接处理：

from docx import Document import io file_bytes = get_file_from_somewhere() # 假设是bytes doc = Document(io.BytesIO(file_bytes)) doc.save("output.docx")

这里要注意一个容易迷惑的点：Document("template.docx")并不会锁定原文件，你后续的所有修改都是基于内存对象的，只有调用doc.save()时才会真正写入磁盘。也就是说，修改一个已有的模板文档时，可以直接doc.save("新文件.docx")另存为一份新文档，原模板保持不变。我一般习惯保持模板文件只读，每次生成都另存为带日期或编号的新文件，这样不怕把模板改坏，重复执行时结果也可预期。

保存时如果目标目录不存在，会直接抛异常，需要提前创建目录。路径中包含中文一般没问题，但要注意Python编码环境，在Windows下命令行跑脚本时建议文件头加上# -*- coding: utf-8 -*-，虽然Python3默认UTF-8，但有时候IDE和控制台环境不一致，加上无妨。

2.2 读取段落与文字

读取是修改和检查的基础。一个Word文档的主体内容主要由段落构成，每个段落里又包含若干个run，run就是同一段落里具有相同格式的一段文字。

下面这段代码把文档里的所有段落文本打印出来，顺带检查每个段落的样式名：

from docx import Document doc = Document("input.docx") for para in doc.paragraphs: print(f"段落样式: {para.style.name} | 文本内容: {para.text}")

如果要进一步读取每个run的文字格式，就遍历para.runs：

for para in doc.paragraphs: for run in para.runs: print(run.text, run.font.size, run.font.bold, run.font.name)

这里要提醒一个小细节，para.text返回的是段落内所有run文本的拼接结果，它不包含任何格式信息。如果你想只读取特定样式的run文本，比如只拿加粗部分的文字，那就必须遍历runs，逐个判断run.font.bold。

如果想按位置定位某个段落，可以用索引，比如doc.paragraphs[0]拿到文档第一个段落。但实际工作中文档位置往往不固定，更可靠的办法是按内容查找，比如遍历段落，判断关键词是否在文本里，找到后再拿这个段落对象做后续修改或在其后面插入新内容：

target_para = None for para in doc.paragraphs: if "合同编号" in para.text: target_para = para break if target_para is not None: print("找到了:", target_para.text)

2.3 写入段落与标题

写入是python-docx最常用的能力。最基础的是追加新的段落：

doc.add_paragraph("这是新段落")

也可以指定样式，比如把段落设成Title或Heading 1这类内置样式：

doc.add_heading("第一章 项目背景", level=1) doc.add_heading("1.1 需求分析", level=2)

add_heading里的level参数就是标题级别，1对应一级标题，2对应二级标题。如果你不想用内置的标题样式，想完全用自己的字号、字体，直接doc.add_paragraph("自定义大标题").style = doc.styles["Title"]，或者不用样式，直接在run上设字号。

段落里追加带格式的文字通过add_run来实现：

para = doc.add_paragraph() run = para.add_run("这是一句带格式的文字") run.font.bold = True run.font.size = docx.shared.Pt(14)

注意一点，add_paragraph()和add_heading()都只能追加到文档末尾，这是python-docx在主体末尾追加的机制决定的。如果你想在文档中间某个位置插入新段落，没有直接的API。解决办法通常是，先记录目标段落的位置节点，然后用目标段落的insert_paragraph_before()方法：

new_para = target_para.insert_paragraph_before("这是插在前面的话") new_para.style = doc.styles["Normal"]

还有一个很隐蔽的问题：add_paragraph()返回的段落对象，其add_run()方法追加的run是在这个段落对象的末尾，同一个段落内多个run之间如果有插入文本的需求，也需要自己控制顺序。一个常见技巧是先把段落的所有run文本拼起来，用完再重新赋值到第一个run，其余run清空，相当于用一次覆盖操作完成文本替换，下面会重点讲。

3. 格式与样式：从“能写”到“写得好”

3.1 字符级格式设置

字符格式的核心对象是Run。它能控制的属性包括字体、字号、加粗、斜体、下划线、删除线、颜色、上下标等，而且每个run可以独立设置，这就意味着同一段落内部可以出现多种混合样式。

下面这段代码演示了常用的设置方式：

from docx.shared import Pt, RGBColor from docx.enum.text import WD_UNDERLINE run = doc.add_paragraph().add_run("关键信息") run.font.name = "微软雅黑" run.font.size = Pt(12) run.font.bold = True run.font.italic = False run.font.underline = WD_UNDERLINE.SINGLE run.font.color.rgb = RGBColor(0xCC, 0x00, 0x00) run.font.strike = True # 删除线

这里有个中文场景下非常容易踩的坑：设置run.font.name = "微软雅黑"，你会发现Word里英文和中文字体表现不一致，甚至中文字体根本没生效。原因是Word的字体设置分为西文字体（w:ascii）和东亚字体（w:eastAsia）两个属性，python-docx的font.name操作的是ASCII和hAnsi部分，中文要用通过更底层的方式设置eastAsia属性：

from docx.oxml.ns import qn run = doc.add_paragraph().add_run("中文字体测试") run.font.name = "微软雅黑" run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")

设置颜色时，RGBColor接受十六进制整数或者直接用RGBColor(255, 0, 0)。要注意颜色的生效时效性，有些旧版Word渲染部分颜色时会根据主题颜色覆盖，如果你设置了不生效，检查一下是否是用了主题颜色导致，直接指定RGB是更可控的方式。

另外，下标和上标操作也很常用：

run_sub = para.add_run("H") run_sub.font.subscript = True run_sup = para.add_run("2") run_sup.font.superscript = True

化学式和数学公式经常这样处理。

3.2 段落级格式设置

段落格式控制的是整段的排版属性，主要包括对齐方式、行距、段前段后间距、缩进等。这些属性都在paragraph_format对象上。

实际项目中我常遇到的行距和缩进控制如下：

from docx.shared import Pt, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING para = doc.add_paragraph("这一段用于演示段落格式设置") pf = para.paragraph_format # 对齐方式：左对齐、居中、右对齐、两端对齐 pf.alignment = WD_ALIGN_PARAGRAPH.CENTER # 行距：固定值20磅，或者倍数1.5倍 pf.line_spacing = Pt(20) # 或者 pf.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE # 段前段后间距 pf.space_before = Pt(12) pf.space_after = Pt(12) # 首行缩进：两字符一般用Pt(24)，也可以用Cm pf.first_line_indent = Pt(24)

设置对齐时有个容易弄混的地方。WD_ALIGN_PARAGRAPH.LEFT不等于默认对齐，默认对齐通常是JUSTIFY（两端对齐），两者在纯中文文本里看起来区别不大，但英文文本可能会因为单词间距拉伸产生明显差异。建议对中文正式公文统一使用两端对齐，对中文标题居中，对重点句使用左对齐。

段落里的换行和特殊符号也有说法。如果你只是想在段内换行，不要用add_paragraph()新建段落，那样会把内容拆成两个段落，影响行距和编号逻辑。正确做法是在同一个段落的run里插入换行符：

run = para.add_run("第一行文字") run.add_break() # 段内换行 run.add_text("第二行文字")

分页符也是类似逻辑，用一个特殊的分页符对象插入，具体可以通过XML操作实现，但如果你只是要做“另起一面”的效果，更稳妥的方式是给段落设置“段前分页”属性。这个属性在python-docx里没有现成API，需要通过paragraph_format.page_break_before = True控制：

para.paragraph_format.page_break_before = True

这样当前段落会自动放在新一页的开始位置，比插入分页符更灵活，因为分页符插在哪里会跟着内容走，而段前分页是段落属性，不会在增删内容时乱跑。

3.3 样式对象与文档主题

除了逐段逐run设置，python-docx提供了样式（Style）体系。每个文档内部有一系列样式，比如Normal、Heading 1、Heading 2等，你可以直接修改样式定义，然后让所有引用了该样式的段落自动生效。

比如把文档默认字体全局改成宋体小四：

style = doc.styles["Normal"] font = style.font font.name = "宋体" font.size = Pt(12) style.element.rPr.rFonts.set(qn("w:eastAsia"), "宋体")

把一级标题改成黑体三号居中：

heading1 = doc.styles["Heading 1"] heading1.font.name = "黑体" heading1.font.size = Pt(16) heading1.element.rPr.rFonts.set(qn("w:eastAsia"), "黑体") heading1.paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER

这里建议你形成自己的“样式驱动”习惯。我知道了API可以直接在run上设置字体和字号，但每次都要重复设置一遍格式字段，后续要调整所有标题的颜色或字号时，就得全局搜索替换。而用样式控制，只需修改一个样式对象，所有引用该样式的段落都会更新，维护成本大幅降低。

有个细节要注意，如果你在run上直接设置了字体属性，它会“覆盖”样式定义，优先级更高。所以如果你发现某个段落样式改了但界面上字体没变化，八九不离十是那一段里有过直接run级格式设置，覆盖了样式值。排查时先检查run.font有没有设过值。

4. 表格、图片与页面设置：常见办公要素的自动化

4.1 表格创建与数据填充

表格是Word文档里比样式更容易出问题的部分。python-docx提供了一个最高频的方法，add_table()，但它的默认行为是带一点的坑：

table = doc.add_table(rows=3, cols=3) table.style = "Table Grid" # 这一步决定了边框是否显示

我刚才写的时候故意没加style这一行。默认新建的表格是不显示边框线的，很多新手以为表格创建失败，实际上是因为没指定Table Grid样式。要先通过table.style = "Table Grid"给表格应用一个内置的“网格”样式，边框就出来了。

填充单元格数据的方式是直接操作table.cell(row, col)：

table.cell(0, 0).text = "姓名" table.cell(0, 1).text = "部门" table.cell(0, 2).text = "工时"

如果你要批量把Python列表或pandas DataFrame的数据填进去，可以写一个通用函数：

def fill_table_from_data(table, data): """data为二维列表，第一行作为表头""" for i, row in enumerate(data): for j, value in enumerate(row): cell = table.cell(i, j) cell.text = str(value)

使用方式：

data = [["姓名", "部门", "工时"], ["张三", "研发部", "40"], ["李四", "运维部", "35"]] fill_table_from_data(table, data)

表格的列宽设置也是经常让人困惑的地方。直接table.columns[0].width = Cm(3)有时候不生效，因为Word的表格列宽需要每一格的cell.width都保持一致才稳定。更可靠的做法是逐单元格设置：

def set_col_widths(table, widths): for j, width in enumerate(widths): for row in table.rows: row.cells[j].width = width set_col_widths(table, [Cm(3), Cm(4), Cm(3)])

4.2 单元格合并与样式调整

合并单元格在构建复杂表头时几乎一定会用到，比如一个跨多列的表头标题：

# 合并第一行的第1、2、3列 merged_cell = table.cell(0, 0).merge(table.cell(0, 2)) merged_cell.text = "人员信息总表"

合并之后的单元格对象，你可以继续设置字体、对齐等：

merged_cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

表格内的单元格本质上有自己的段落列表，操作方式和普通段落一致。比如给某个单元格的文字加粗并居中显示：

cell = table.cell(1, 0) cell.paragraphs[0].text = "" # 清掉默认文本占位 run = cell.paragraphs[0].add_run("张三") run.font.bold = True cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

这里有个小坑，直接对cell.text赋值时，python-docx实际上会清除该单元格原有段落，创建一个新段落，然后把文本写进去。所以如果这个单元格里原来有复杂样式，赋值操作会把样式清掉。保留样式的方法是先获取原段落对象，用paragraph.text = "新值"或者清空runs再添加新run，而不是直接给cell.text赋新值。

单元格底色设置稍微底层一点，需要通过shd元素控制：

from docx.oxml.ns import qn from docx.oxml import OxmlElement def set_cell_bg_color(cell, color_hex): tcPr = cell._tc.get_or_add_tcPr() shd = OxmlElement("w:shd") shd.set(qn("w:val"), "clear") shd.set(qn("w:color"), "auto") shd.set(qn("w:fill"), color_hex) tcPr.append(shd)

调用示例：

set_cell_bg_color(table.cell(0, 0), "D9E2F3")

实现表头灰底、正文白底等效果就靠这个。

4.3 插入图片与图文混排

python-docx的图片插入API很直白：

doc.add_picture("chart.png", width=Cm(14))

但如果只是这么写，图片默认会加上一个单独的段落，并且默认左对齐。如果想居中排布，可以这样处理：

from docx.shared import Cm from docx.enum.text import WD_ALIGN_PARAGRAPH pic_para = doc.add_paragraph() pic_run = pic_para.add_run() pic_run.add_picture("chart.png", width=Cm(14)) pic_para.alignment = WD_ALIGN_PARAGRAPH.CENTER

图片大小的控制参数可以只给宽度，高度会按原始比例自动缩放；如果你给了宽度和高度两个值，Python不会保证按比例缩放，有可能会把图拉伸变形。如果原图比例和你要的显示尺寸不一致，建议先只给宽度，让高度自适应，这样不会变形。

批量插入图片时建议先检查文件是否存在、扩展名受不受支持。python-docx支持常见的jpg、png、gif、bmp等格式，但如果你传了一个不存在的路径，报错信息会非常绕，所以先判一下文件是否存在会更省事。

图片插入还有个对齐细节。用doc.add_picture()插入时会自动创建独立段落，但这个段落没有保留上下文，如果你想在既有段落里的文字后面紧跟图片（比如文字和图标在同一行），那就要用上面那段add_run().add_picture()的做法，把图片加进run里，而不是用doc级方法。

4.4 页面设置与页眉页脚

页面设置主要通过section对象来控制。一个文档可以有多个分节，每个分节都有独立的页面设置，默认新建的文档只有一个section：

section = doc.sections[0] # 页面大小：A4 section.page_width = Cm(21) section.page_height = Cm(29.7) # 页边距 section.left_margin = Cm(2.5) section.right_margin = Cm(2.5) section.top_margin = Cm(2.5) section.bottom_margin = Cm(2.5)

如果想让文档横向布局，只需要把宽度和高度值对调即可。有些报告有“部分页面横向”的需求，那就需要给不同内容新建section，再分别设置方向。如果在一个section里混排，会非常难处理。

页眉页脚的写入类似：

header = section.header paragraph = header.paragraphs[0] paragraph.text = "公司内部文档" paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER footer = section.footer footer.paragraphs[0].text = "机密文件，请勿外传"

页码的插入比较复杂，因为页码本质上是一个动态域（field），不是静态文本。python-docx没有直接提供插入页码的API，需要通过XML原生方式插入域代码。常规做法是手动构造w:fldSimple元素或w:instrText元素，我一般用下面这个辅助函数：

from docx.oxml.ns import qn from docx.oxml import OxmlElement def add_page_number(paragraph): run = paragraph.add_run() fldChar1 = OxmlElement("w:fldChar") fldChar1.set(qn("w:fldCharType"), "begin") instrText = OxmlElement("w:instrText") instrText.set(qn("xml:space"), "preserve") instrText.text = "PAGE" fldChar2 = OxmlElement("w:fldChar") fldChar2.set(qn("w:fldCharType"), "end") run._r.append(fldChar1) run._r.append(instrText) run._r.append(fldChar2)

调用方式：

footer = section.footer para = footer.paragraphs[0] para.text = "第 " add_page_number(para) para.add_run(" 页")

这里补充说明一下，这样插入的页码在Word里打开后会自动显示成当前页码；如果你用python-docx读回段落文本，看到的可能是空字符串或域代码占位，这是正常现象，不代表没生效。也有一个情况是Word打开后某个域不会自动刷新，需要按Ctrl+A全部选中再按F9更新域，不过PAGE域在打开文档时一般会自动刷新。

页眉里有一条默认的横线，很多公司模板不需要它，但内置样式里它就在那里，去掉的方法是通过样式定义修改边框。具体操作是将页眉段落的下边框取消，这个实现比较底层，我一般是直接在模板文件里用Word改好页眉再让python-docx填充数据，命令行脚本里尽量不深度处理页眉边框。

5. 批量生成实战：以“月度巡检报告自动生成”为例

5.1 场景拆解与流程设计

批量生成是python-docx最能体现价值的地方。我拿一个常见的“月度巡检报告自动生成”场景举例吧。假设巡检组每个月要出具N份设备巡检报告，格式完全一致，只有设备编号、巡检人、日期、状态描述、数据明细这些字段不同。

如果手工做，需要先复制上一月的文档，再逐条改文本、改表格、改图片，一小时能处理二三十份算运气好。用python-docx可以做到几分钟生成几百份。

设计流程上，我强烈建议采用**“模板 + 占位符 + 数据驱动”**的思路，而不是从头用代码搭建全部文档结构。原因有两个。第一，模板文件用Word做，版式、页眉页脚、字体颜色这些复杂样式可以直接可视化调好，精度远高于代码一条条设置。第二，代码只负责做“替换”和“填充”动作，逻辑简单，出问题的概率小。

流程拆成四步：

1. 准备一份设计好的模板docx，里面用特殊标记标注变量区域，比如{{设备编号}}、{{巡检人}}、{{日期}}。
2. 准备数据，来源于Excel、数据库或Python字典列表。
3. 对每一条数据，复制模板文件，打开，替换占位符，插入或更新表格。
4. 按命名规则保存到目标目录。

5.2 模板占位符替换实现

占位符替换的核心难点是：由于用户无法预测文本在docx的run里如何分布，直接对整个段落的文本做“字符串替换”不可靠。比如一个占位符{{设备编号}}在Word里可能被分割成多个run存放，常见的拆分原因是Undo、拼写检查、追加编辑等。

保险的做法是处理单位缩小到“段落级”，先把段落的全部run文本合并，替换完后再写回去。实现思路如下：

def replace_placeholders_in_paragraph(paragraph, replacements): """在段落级完成占位符替换，避免run级拆分问题""" full_text = paragraph.text if not any(key in full_text for key in replacements): return False new_text = full_text for key, value in replacements.items(): new_text = new_text.replace(key, value) # 清空原有所有run中的文字，把合并文本写入第一个run if paragraph.runs: paragraph.runs[0].text = new_text for run in paragraph.runs[1:]: run.text = "" return True

需要注意，这种方法会把段落里所有run的格式统一成第一个run的格式，这是它的代价。如果这个段落里只有占位符一种格式，那没问题；如果同一段里混了加粗和普通文字，并且你还想保留这种混排，就需要更精细的处理，例如分段处理或者用更复杂的run分配逻辑。对大多数模板段落来说，一个段落就是一个文本块，牺牲一点格式换取代码简洁是可以接受的。

对整个文档操作时，把所有段落过一遍：

def replace_all(paragraphs, replacements): for para in paragraphs: replace_placeholders_in_paragraph(para, replacements)

需要特别提醒的是，你要注意模板里的占位符字符，如果包含中文，记得确保模板文档内这些字符没有被Word自动拆成多个run的情况。在Word里写{{设备编号}}一般是一次性输入的，通常是一个run，但如果你在Word里做了撤销、修订等操作，就有概率被拆开。遇到这种情况，先用第2.2节的方法读一遍段落runs结构，就能看到拆分情况。

5.3 完整代码示例：批量生成巡检报告

下面这是一个完整的批量生成脚本框架，可直接套用你自己的模板和数据。

import os import copy from docx import Document # 数据可以来自Excel/csv/数据库，这里用字典列表模拟 report_data = [ { "device_id": "EQ-001", "inspector": "张三", "date": "2025-01-05", "status": "运行正常", "temperature": "36.5℃", "remark": "建议日常维护", }, { "device_id": "EQ-002", "inspector": "李四", "date": "2025-01-05", "status": "运行正常", "temperature": "38.2℃", "remark": "风扇噪声偏大，需关注", }, ] template_path = "report_template.docx" output_dir = "output_reports" os.makedirs(output_dir, exist_ok=True) def render_report(record): doc = Document(template_path) replacements = { "{{device_id}}": record["device_id"], "{{inspector}}": record["inspector"], "{{date}}": record["date"], "{{status}}": record["status"], "{{temperature}}": record["temperature"], "{{remark}}": record["remark"], } # 替换正文段落 for para in doc.paragraphs: replace_placeholders_in_paragraph(para, replacements) # 替换表格中的占位符 for table in doc.tables: for row in table.rows: for cell in row.cells: for para in cell.paragraphs: replace_placeholders_in_paragraph(para, replacements) filename = f"{record['device_id']}_巡检报告.docx" doc.save(os.path.join(output_dir, filename)) print("已生成:", filename) for item in report_data: render_report(item)

这段代码里有两个细节值得展开解析。第一个是“表格里的占位符也要处理”。很多人的模板里数据表格带有{{temperature}}这种占位符，如果你只处理doc.paragraphs，表格里的内容是不会被触及的，必须再嵌套一层遍历表格单元格的段落，这是最容易漏掉的地方。第二个是“生成文件命名最好包含唯一业务键”。用device_id做文件名，可以避免重名覆盖，同时方便后面按设备追踪。

如果模板内容很多，replace_placeholders_in_paragraph函数在每次调用时会遍历整段落的所有run，性能略微可以接受，但如果单文档有几百个占位符，建议对每个段落先做一次包含判断，不合格的段落直接跳过处理，就是我在函数里加if not any(key in full_text ...)这一步的原因，能省掉不必要的大量字符串替换。

5.4 高性能批量与并发思考

上面的脚本一次只能处理一条数据，如果数据量达到几千条，推荐并发处理。但并发有一个必须注意的限制：python-docx操作同一个模板文件时，如果没有做锁保护，容易因为文件句柄访问同源模板产生问题。更稳妥的方式是先读取模板到内存，然后每个线程独立用内存数据去创建Document：

with open(template_path, "rb") as f: template_bytes = f.read()

导出函数内部改成用io.BytesIO(template_bytes)初始化文档，这样每条数据都是独立的文件对象。再用concurrent.futures.ThreadPoolExecutor控制并发，在几百条到几千条的规模上都不会有任何压力。

但也要记住，批量生成完之后建议打开样本做一次抽查验证，比如检查占位符是否全部被替换，有没有残留{{xxx}}。残留的常见原因是模板里占位符跨段落或者跨表格单元格，导致替换函数没匹配到，这也从侧面验证了上面为什么强调“段落级检查”之后还要“全文档扫描残留”。一个简单的残留检查就是当前文档里的文本如果还包含{{，说明替换失败。

6. 常见问题与排查技巧

6.1 高频问题速查表

我把过去遇到的高频问题和解决思路整理成了表格，方便你排查时直接对照。

6.2 调试技巧：读回验证与结构可视

排查python-docx问题最有体感的方法是“读回验证”。这个思路其实很朴素：你写入文档之后，再用python-docx把它打开，把关键内容打出来，确认写入和替换是否符合预期。比如批量生成后检查已生成文档里的所有段落和表格内容：

def dump_doc_structure(path): doc = Document(path) print(f"==== {path} ====") for i, para in enumerate(doc.paragraphs): print(f"P{i}: {para.text}") for t, table in enumerate(doc.tables): print(f"Table {t}: {len(table.rows)}x{len(table.columns)}") for row in table.rows: cells = [cell.text for cell in row.cells] print(cells)

这个函数非常适合做自动化测试的校验节点。因为它不吃Word软件，在服务器和CI环境里也能直接跑，所以能提前发现很多“肉眼看了模板觉得没问题，但程序跑出来不对”的情况。

如果你要精细排查run级的拆分问题，可以写一个简单的遍历函数，打印每一段的run列表和每个run的文本长度，用这种方式确认究竟是哪个run包着占位符，也能顺序看出Word是否把文本切成了几段。

6.3 排查思路总结与进阶方向

遇到错误时，我的排查顺序通常是：先定位报错在哪个API，比如add_table、save还是加图；然后查操作对象是否脱离了文档上下文，比如拿了一个表格的单元格，但后来对文档新增了分节，导致引用指向了不存在的结构；最后再怀疑是格式属性的兼容性问题，比如设置的某个颜色或字体在当前Word版本中不显示。大多数问题到第二步就能解决。

如果你做的是复杂文档，进阶方向可以考虑如下几个：

• 用docxtpl做模板引擎，它把占位符替换和多值表格循环都做了封装，对“一人填多条数据”的批量场景很合适。
• 把报告内容与pandas、openpyxl、matplotlib联动，数据准备用DataFrame，图表用matplotlib生成png，再用python-docx插入图片，整条链路能直接自动化输出正式报告。
• 批量生成之后需要PDF归档的话，python-docx做不到渲染，但可以在服务器上装LibreOffice，然后命令行调用LibreOffice --headless --convert-to pdf，实现批量转PDF。这在Linux服务器上很常用。
• 如果模板中有更复杂的动态表格行数、动态合并单元格，模板机制会不够用，那就需要写一个“表格构建函数”来自行组装，通过按行复制单元格结构、填充数据、调节样式来完成。这条跳过直接改动XML才能解决的场景，在实际业务里很少遇到。

7. 最后再分享一点实际经验

从最早在项目里手动改Word模板，到后面几百条数据批量自动生成报告，python-docx帮了大忙，但我更要强调的是规范习惯。始终把模板文件当作“只读资源”，永远生成新文件；始终用样式驱动而不是每次硬编码格式；始终在批量逻辑结束后做一轮自动校验。这三点做到了，即使文档种类翻一倍，代码改动的成本也很可控。

另外，如果你的使用频率很高，建议把常用的操作封装成一个小工具模块，比如doc_utils.py，里面放set_run_font、fill_table_from_data、set_cell_bg_color、replace_placeholders_in_paragraph这类函数，长期来看能省大量重复代码。下次遇到类似需求，直接复用即可。如果要用到动态图表，也可以把图表和表格数据来源统一从一个数据函数里获取，保持数据链路的一致性。

踩过几次坑之后，我现在的做法就稳定了：先设计模板，写好占位符，再用脚本填充，最后打开几份成品检查版式。这个流程在很多场景下已经被验证是高效、可靠且好维护的。希望这篇内容能帮你少走弯路。