如何使用python-docx添加pandas提取的Excel变量文本？

首先纠正认知偏差：document.add_paragraph() 不存在「仅支持固定文本、不能传入变量」的限制，只要传入的第一个位置参数是字符串类型（或可隐式转换为字符串的类型），无论是硬编码的固定文本还是存储动态值的变量，都可以正常写入。你遇到的报错/写入异常基本都是变量类型、作用域问题导致的。

完整实现流程（pandas读Excel + 动态写Word） #

• 第一步：安装所需依赖

pip install pandas python-docx openpyxl

• 第二步：用pandas提取Excel中的动态数据

import pandas as pd
from docx import Document

# 读取目标Excel文件，替换为自己的文件路径
df = pd.read_excel("业务数据.xlsx")

# 按需提取动态内容，以下是常见场景示例
# 1. 提取单个标量值存为变量
first_product = df.loc[0, "产品名"]
monthly_revenue = df["营收"].sum()
# 2. 批量生成多行结构化内容
record_lines = []
for idx, row in df.iterrows():
    line = f"序号{idx+1} | 产品：{row['产品名']} | 销量：{row['销量']} | 营收：{row['营收']}元"
    record_lines.append(line)

• 第三步：将动态内容写入Word文档

# 新建空白Word文档
doc = Document()

# 直接传入变量写入段落，和传入固定文本的写法完全一致
doc.add_heading("月度业务数据统计", level=1)
doc.add_paragraph(f"本次统计首个录入产品为：{first_product}")
doc.add_paragraph(f"当月总营收合计：{monthly_revenue}元")

doc.add_heading("明细记录", level=2)
# 遍历动态内容列表批量生成段落
for line in record_lines:
    doc.add_paragraph(line)

# 如果需要给段落内部分内容设置格式（比如局部加粗、改字体颜色），可以通过add_run拆分写入
p = doc.add_paragraph()
p.add_run("文档生成时间：").bold = True
p.add_run(f"{pd.Timestamp.now().strftime('%Y年%m月%d日')}")

# 保存最终文档
doc.save("业务数据统计报告.docx")

常见异常排查 #

如果传入变量时出现报错、写入内容不符合预期，优先检查以下问题：

• 变量作用域错误：调用add_paragraph()的代码位置无法访问到你定义的变量，触发NameError，和函数本身是否支持变量无关
• 传入pandas对象而非具体值：直接把DataFrame、Series这类对象作为参数传入，会写入对象的内存地址而非实际内容，需要用.loc、.iloc、.values提取到具体标量，或者转成格式化后的字符串再传入
• 变量类型不匹配：传入字典、列表等无法自动转换为可读字符串的对象时，需要先手动序列化为目标文本格式再传入

内容的提问来源于stack exchange，提问作者guy estragon