python-docx不能直接替换模板变量，需手动遍历run按格式拆分替换{key}占位符，避免用{{key}}；替换时须保留原run字体样式，中文需显式设置中文字体如"SimSun"。
python-docx 能不能直接替换模板里的变量
不能。python-docx 没有内置的「变量替换」功能，它只提供底层文档对象操作能力。所谓“填充模板”，本质是遍历段落、表格、文本框中的 run 或 paragraph.text，手动查找并替换占位符（比如 {name}、{{phone}}）。如果你期待像 Jinja2 那样写 {{ user.name }} 自动渲染，得自己封装逻辑或换库。
为什么推荐用 {key} 而不是 {{key}} 作为占位符
因为 {{key}} 容易和 python-docx 内部使用的 docx2python 或某些解析器冲突，更关键的是：Word 的查找替换 API（包括 python-docx 的 paragraph.text.replace()）对花括号敏感——如果段落里有加粗、颜色、超链接等格式，直接 replace 会破坏 run 结构，导致格式错乱甚至丢失。
- 用
{name}更安全：单层花括号在 Word 中极少原生出现，误匹配概率低 - 替换时必须按
run粒度操作，不能只改paragraph.text—— 否则加粗字变普通、中文后多空格、项目符号消失 - 如果模板里已有
{或}字符（比如代码片段），需提前转义或改用其他分隔符如[[name]]
如何安全地替换段落中带格式的 {xxx} 占位符
核心是「不破坏 run 链」：找到包含占位符的 run，拆分它，插入新文本 run，保留原格式。下面是最简可行逻辑：
def replace_in_paragraph(paragraph, key, value):
full_text = paragraph.text
if f"{{{key}}}" not in full_text:
return
for run in paragraph.runs:
if f"{{{key}}}" in run.text:
# 拆分 run：前缀 + 占位符 + 后缀
parts = run.text.split(f"{{{key}}}")
run.text = parts[0] # 前缀
new_run = paragraph.add_run(str(value))
new_run.bold = run.bold
new_run.italic = run.italic
new_run.font.size = run.font.size
if len(parts) > 1:
paragraph.add_run(parts[1]) # 后缀
break
- 这个函数只处理第一个匹配项；多次出现需循环调用或改用正则 + 多次 split
- 没处理表格单元格（
cell.paragraphs）、页眉页脚（section.header.paragraphs）、文本框（需遍历shape.text_frame.paragraphs） - 值为 None 或数字时，
str(value)是必须的，否则paragraph.add_run(None)会报错
遇到「替换后中文显示为方框」或「字体变了」怎么办
这是最常被忽略的坑：python-docx 默认不继承模板字体，新插入的 run 会使用默认西文字体（通常是 Calibri），而中文需要显式指定中文字体（如 "SimSun" 或 "Microsoft YaHei"）。
- 替换时务必复制原
run.font.name，但注意：中英文字体常不同，run.font.name可能返回None或英文名 - 稳妥做法是统一设置：
new_run.font.name = "SimSun"，再补一句new_run._element.rPr.rFonts.set(qn("w:eastAsia"), "SimSun")（需导入from docx.oxml.shared import qn） - 如果模板用了主题字体（Theme Fonts），新 run 不会自动继承，只能硬编码字体名
复杂点在于：一个段落可能混合宋体、微软雅黑、加粗标题，真正健壮的填充需分析每个 run 的实际生效字体，而不是简单拷贝 run.font.name。这已经超出轻量填充范畴，建议此时转向 docxtpl 库——它内建字体继承和复杂结构支持，但代价是模板语法要迁移到 {% for ... %} 风格。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
