Python使用Python-docx创建和写入Word文档基础教程
在自动化报表生成、批量通知打印和合同文档排版等实际场景中，直接通过脚本生成规范的 Microsoft Word（.docx）文件能够节省大量重复劳动。Python 社区中的 python-docx 是处理此类任务的标准工具库。它不依赖本地安装的 Office 软件，直接通过解析和封装 OpenXML 标准来读取、修改与创建 Word 文档。本文将按照真实的开发步骤，拆解文档核心层级，讲解段落、字符块及表格的写入方式，并梳理常见排版与运行异常的防范策略。
一、核心模型：理解 Word 文档的层级结构
初学者使用 python-docx 时，最常见的困惑往往来源于格式设置不生效。例如想要改变某句话的字体颜色，却发现直接修改段落属性并不起作用。这种现象源于 Word 文档严密的树状层级模型：文档并非单一的纯文本流，而是由多层容器嵌套而成的对象集合。
在 python-docx 中，主要的层级关系如下：
- Document（文档）：最顶层的容器，管理整个文档的节（Section）、全局默认样式、内嵌图片及主数据流。
- Section（节）：定义页面几何属性，如纸张尺寸、页面纵向或横向排布、页边距以及页眉页脚。
- Paragraph（段落）：块级容器。负责段落级的对齐方式（居中、左对齐）、行高倍数、段前段后间距以及首行缩进。
- Run（字符运行块）：段落内部的最小排版单元。一个段落可以包含多个 Run，同一 Run 内的所有字符共享完全一致的字形属性（字体、字号、加粗、颜色、下划线）。
- Table（表格）：由 Row（行）和 Cell（单元格）组成，每个单元格内部又可以独立容纳段落与新的文本。
二、快速起步：安装与创建空白文档
在使用之前，请确保 Python 环境为 3.8 或更高版本。在终端中执行以下命令进行安装：
pip install python-docx注意，安装的包名为带有连字符的 python-docx，但在 Python 代码中导入时，包名为不带连字符的 docx。初学者容易混淆这一点，导致 ModuleNotFoundError。
下面是一个最简可运行示例，演示了如何创建文档、添加各级标题和正文段落，最后持久化到本地磁盘：
from docx import Document
# 1. 实例化一个全新的空白文档
doc = Document()
# 2. 写入文档大标题 (level 0 代表 Title 样式)
doc.add_heading('系统运行周度汇报', level=0)
# 3. 写入一级小节标题 (level 1 代表 Heading 1)
doc.add_heading('一、本周服务运行概况', level=1)
# 4. 追加基础正文段落
doc.add_paragraph('本周生产环境整体运行平稳，核心 API 可用率达到 99.98%，无重大事故报告。')
# 5. 保存文档到目标路径
doc.save('weekly_report.docx')
执行 doc.save('weekly_report.docx') 时，如果该文件已在 Microsoft Word 或 WPS 中处于打开状态，操作系统会对该文件施加独占写锁，Python 将直接抛出 PermissionError: [Errno 13] Permission denied。在调试阶段，必须在重新执行脚本前关闭对应的 Word 窗口，或在保存前为输出文件名追加时间戳后缀。
三、精准排版：段落控制与 Run 字符样式分离
很多开发者在生成文档时需要富文本支持，例如“同一行中只有关键词标红加粗，其余文字保持常规灰色”。必须通过 Paragraph.add_run() 分割不同的文本片段来实现。
以下代码展示了如何在一个段落内组合普通文字与强调文字，并配置段前段后间距与行高：
from docx import Document
from docx.shared import Pt, RGBColor, Inches
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
doc = Document()
p = doc.add_paragraph()
# 1. 设置段落级排版属性
p.alignment = WD_PARAGRAPH_ALIGNMENT.LEFT
p.paragraph_format.space_before = Pt(6) # 段前间距 6 磅
p.paragraph_format.space_after = Pt(12) # 段后间距 12 磅
p.paragraph_format.line_spacing = 1.25 # 1.25 倍行距
# 2. 依次追加不同样式的 Run
run1 = p.add_run('【警示信息】')
run1.bold = True
run1.font.size = Pt(11)
run1.font.color.rgb = RGBColor(166, 108, 91) # 强调赭红色
run2 = p.add_run('当前集群节点内存使用率已突破 ')
run2.font.size = Pt(10.5)
run3 = p.add_run('85% 警戒阈值')
run3.bold = True
run3.font.underline = True
run3.font.color.rgb = RGBColor(82, 103, 125) # 主色蓝灰
run4 = p.add_run('，请运维人员尽快核查。')
run4.font.size = Pt(10.5)
doc.save('alert.docx')
解决中文字体设置不生效的问题
很多读者会发现，通过 run.font.name = '微软雅黑' 设置后，导出的文档在 Word 中查看仍然是默认的宋体或等线。这是因为 Word 内部对西文字体（ascii）与中文字体（eastAsia）使用了不同的 XML 属性标签。要让中文字体切实生效，必须同时配置 OpenXML 底层命名空间：
from docx.oxml.ns import qn
def apply_chinese_font(run, font_name='Microsoft YaHei', font_size_pt=10.5):
"""同时设置西文与中文字体兼容映射"""
run.font.name = font_name
run._element.rPr.rFonts.set(qn('w:eastAsia'), font_name)
run.font.size = Pt(font_size_pt)
四、结构化数据：创建与写入表格
除了文本段落，在业务文档中输出结构化数据同样是核心场景。通过 doc.add_table(rows, cols) 可以快速插入一个初始网格。
from docx import Document
doc = Document()
doc.add_heading('服务器节点资源清单', level=2)
# 创建 1 行 3 列的表格结构
table = doc.add_table(rows=1, cols=3)
table.style = 'Table Grid' # 使用带细边框的经典表格样式
# 填充表头行
hdr_cells = table.rows[0].cells
hdr_cells[0].text = '节点编号'
hdr_cells[1].text = '内网 IP'
hdr_cells[2].text = 'CPU / 内存规格'
# 数据列表
data = [
('node-app-01', '192.168.10.11', '8 Core / 32 GB'),
('node-app-02', '192.168.10.12', '8 Core / 32 GB'),
('node-db-01', '192.168.10.21', '16 Core / 64 GB'),
]
# 逐行追加写入
for item in data:
row_cells = table.add_row().cells
row_cells[0].text = item[0]
row_cells[1].text = item[1]
row_cells[2].text = item[2]
doc.save('server_list.docx')
若需要对单元格文字做加粗、变色或居中，可直接获取单元格内部默认创建的段落对象：cell = table.cell(row_idx, col_idx); p = cell.paragraphs[0]，然后按照前述段落与 Run 的规则对其进行格式修饰。
五、实战总结与关键避坑全景
为了便于在日常开发中快速参考与定位问题，下表梳理了 python-docx 核心接口的调用方式及其关键要点：
通过掌握 Document -> Section -> Paragraph / Table -> Run 的逐级包含逻辑，并区分段落级与字符级样式，开发者就能够灵活地在 Python 中构建出整洁、规范且富于视觉层次的 Word 文档。在实际大型项目中，通常推荐“先在 Word 中制作包含预设样式、页眉页脚与封面版式的空白模板文档，再用 Document('template.docx') 加载该模板并动态填入业务内容”，以此兼顾排版专业性与自动化写入的高效性。
免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。
