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的方案其实不少我用实际经验帮你对比一下。win32compywin32通过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文档的主体内容主要由段落构成每个段落里又包含若干个runrun就是同一段落里具有相同格式的一段文字。下面这段代码把文档里的所有段落文本打印出来顺带检查每个段落的样式名from docx import Document doc Document(input.docx) for para in doc.paragraphs: print(f段落样式: {para.style.name} | 文本内容: {para.text})如果要进一步读取每个run的文字格式就遍历para.runsfor 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(第一章 项目背景, level1) doc.add_heading(1.1 需求分析, level2)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(rows3, cols3) 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, widthCm(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, widthCm(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对象来控制。一个文档可以有多个分节每个分节都有独立的页面设置默认新建的文档只有一个sectionsection 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打开后某个域不会自动刷新需要按CtrlA全部选中再按F9更新域不过PAGE域在打开文档时一般会自动刷新。页眉里有一条默认的横线很多公司模板不需要它但内置样式里它就在那里去掉的方法是通过样式定义修改边框。具体操作是将页眉段落的下边框取消这个实现比较底层我一般是直接在模板文件里用Word改好页眉再让python-docx填充数据命令行脚本里尽量不深度处理页眉边框。5. 批量生成实战以“月度巡检报告自动生成”为例5.1 场景拆解与流程设计批量生成是python-docx最能体现价值的地方。我拿一个常见的“月度巡检报告自动生成”场景举例吧。假设巡检组每个月要出具N份设备巡检报告格式完全一致只有设备编号、巡检人、日期、状态描述、数据明细这些字段不同。如果手工做需要先复制上一月的文档再逐条改文本、改表格、改图片一小时能处理二三十份算运气好。用python-docx可以做到几分钟生成几百份。设计流程上我强烈建议采用**“模板 占位符 数据驱动”**的思路而不是从头用代码搭建全部文档结构。原因有两个。第一模板文件用Word做版式、页眉页脚、字体颜色这些复杂样式可以直接可视化调好精度远高于代码一条条设置。第二代码只负责做“替换”和“填充”动作逻辑简单出问题的概率小。流程拆成四步准备一份设计好的模板docx里面用特殊标记标注变量区域比如{{设备编号}}、{{巡检人}}、{{日期}}。准备数据来源于Excel、数据库或Python字典列表。对每一条数据复制模板文件打开替换占位符插入或更新表格。按命名规则保存到目标目录。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_okTrue) 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操作同一个模板文件时如果没有做锁保护容易因为文件句柄访问同源模板产生问题。更稳妥的方式是先读取模板到内存然后每个线程独立用内存数据去创建Documentwith open(template_path, rb) as f: template_bytes f.read()导出函数内部改成用io.BytesIO(template_bytes)初始化文档这样每条数据都是独立的文件对象。再用concurrent.futures.ThreadPoolExecutor控制并发在几百条到几千条的规模上都不会有任何压力。但也要记住批量生成完之后建议打开样本做一次抽查验证比如检查占位符是否全部被替换有没有残留{{xxx}}。残留的常见原因是模板里占位符跨段落或者跨表格单元格导致替换函数没匹配到这也从侧面验证了上面为什么强调“段落级检查”之后还要“全文档扫描残留”。一个简单的残留检查就是当前文档里的文本如果还包含{{说明替换失败。6. 常见问题与排查技巧6.1 高频问题速查表我把过去遇到的高频问题和解决思路整理成了表格方便你排查时直接对照。现象原因解决办法新建表格没有边框未设置表格样式table.style Table Grid设置了中文字体但没生效只设置了ASCII字体没设置eastAsia使用rFonts设置w:eastAsia修改已有文档后样式错乱直接给cell.text赋值清空了原格式改用段落内run逐个替换文本保存时提示PermissionError原文件被Word占用另存为新路径或者关闭Word进程替换占位符时部分没换掉占位符被Word拆在多个run里用段落级合并替换方式处理修改表格列宽无效只设置columns宽度对每个单元格的cell.width设置插入的图片比例变形同时给了宽和高只给宽度高度自动缩放页码读不到具体数字页码是动态域读回是域代码在Word里打开查看用F9刷新域按中文路径打开文件报错环境?编码或权限问题检查目录存在性用绝对路径保证权限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(fP{i}: {para.text}) for t, table in enumerate(doc.tables): print(fTable {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这类函数长期来看能省大量重复代码。下次遇到类似需求直接复用即可。如果要用到动态图表也可以把图表和表格数据来源统一从一个数据函数里获取保持数据链路的一致性。踩过几次坑之后我现在的做法就稳定了先设计模板写好占位符再用脚本填充最后打开几份成品检查版式。这个流程在很多场景下已经被验证是高效、可靠且好维护的。希望这篇内容能帮你少走弯路。