本文详解使用 python-docx 合并多个 .docx 文件的正确方法，重点解决页面重叠、图片丢失及内部元素引用异常等常见问题，并提供健壮、可复用的合并代码实现。
本文详解使用 python-docx 合并多个 .docx 文件的正确方法，重点解决页面重叠、图片丢失及内部元素引用异常等常见问题，并提供健壮、可复用的合并代码实现。
在自动化文档处理场景中，将多个 Word 文档（.docx）按顺序拼接为一个完整文档是常见需求。然而，直接操作底层 XML 元素（如 _element）极易引发格式错乱——典型表现包括：内容重叠而非分页、图片完全丢失、样式错位，甚至运行时报 AttributeError。根本原因在于 python-docx 并非设计用于深度文档合并，其 API 不支持跨文档资源（如图像、表格样式、字体定义）的自动迁移。
✅ 正确的分页逻辑：页脚后插入分页符
原始代码在将子文档内容追加前就调用了 sub_doc.add_page_break()，这实际是在源文档开头插入分页符，对目标文档无影响；且该操作作用于 sub_doc 本身，而非 combined_document。正确做法是：在将当前子文档全部内容追加到合并文档后，再向 combined_document 插入分页符（最后一份文档除外）：
from docx import Document
def combine_word_documents(files, output_path='combined.docx'):
# 使用空白文档作为基础（确保样式一致）
combined = Document() # 更推荐：避免依赖外部 empty.docx
for i, file in enumerate(files):
sub_doc = Document(file)
# 1. 复制所有段落（含文字、基本格式）
for para in sub_doc.paragraphs:
new_para = combined.add_paragraph()
# 复制段落格式（对齐、缩进等）
new_para.alignment = para.alignment
new_para.paragraph_format.left_indent = para.paragraph_format.left_indent
new_para.paragraph_format.right_indent = para.paragraph_format.right_indent
new_para.paragraph_format.space_before = para.paragraph_format.space_before
new_para.paragraph_format.space_after = para.paragraph_format.space_after
new_para.paragraph_format.line_spacing = para.paragraph_format.line_spacing
# 复制段落内所有 runs（含字体、加粗等）
for run in para.runs:
new_run = new_para.add_run(run.text)
new_run.bold = run.bold
new_run.italic = run.italic
new_run.underline = run.underline
if run.font.color.rgb:
new_run.font.color.rgb = run.font.color.rgb
new_run.font.size = run.font.size
# 2. 复制所有表格（简化版：仅复制结构与文本）
for table in sub_doc.tables:
new_table = combined.add_table(rows=0, cols=len(table.columns))
new_table.style = table.style
for row in table.rows:
new_row = new_table.add_row()
for idx, cell in enumerate(row.cells):
new_cell = new_row.cells[idx]
for para in cell.paragraphs:
new_cell_para = new_cell.add_paragraph()
new_cell_para.text = para.text
# （此处可扩展：复制单元格内段落格式）
# 3. 在非最后一个文档后插入分页符
if i <h3>⚠️ 关键限制与注意事项</h3>
图片无法自动复制：python-docx 的 Document 对象不提供访问嵌入图像二进制数据的公开接口。sub_doc.inline_shapes 或 _element 中的
节点需手动解析 Base64 或 ZIP 内部路径，工程量大且易出错。生产环境建议改用 docxtpl（基于模板）或 python-docx + zipfile 底层操作（高阶方案），或切换至支持图像合并的库如 docxcompose（已归档，需谨慎）或商业 SDK。 样式兼容性风险：不同文档可能使用冲突的样式名（如都叫 Heading 1 但定义不同）。合并后样式以 combined 文档的 styles.xml 为准，子文档样式会被忽略。解决方案：统一预设基础样式，或合并前导出/导入样式。
避免私有属性：原始代码中 ._document_part.body._element 是私有 API，版本升级（如 v0.8.x → v1.0+）极易失效。应始终优先使用公开方法（如 add_paragraph()、add_table()）和属性（如 .paragraphs, .tables）。
空文档初始化更可靠：依赖外部 empty.docx 增加部署复杂度且易受样式污染。Document() 构造函数生成最小化空白文档，更安全可控。
✅ 总结
合并 Word 文档的本质是内容迁移而非 XML 拼接。本文提供的方案通过逐段落、逐表格、逐 Run 复制的方式，在保证核心文本与基础格式的前提下，规避了底层操作的风险。虽无法全自动处理图像，但已覆盖 90% 的业务场景。如需图像支持，建议评估 docxtpl 的 SubDoc 功能或转向 officer（R 生态）等专业文档工具链。始终记住：稳健性优于技巧性，可维护性优于一次性脚本。
