单位里最磨人的活儿，大概就是手动生成几十份格式差不多的Word文档了。月初要做考核通报、季度要出项目验收报告、月底要发催款函，甚至一次校园招聘就要给几百个候选人逐个生成面试确认书。手工复制粘贴Excel里的姓名、部门、金额、日期，再微调格式，一个下午就这么没了，效率低不说，心情也极其烦躁。

这套“Sheet to Doc”方案，我用下来最大的感受就是把“Excel里已有的数据”和“Word模板的版式”彻底拆开，中间用JSON做一次数据搬运和整理，最后用一个脚本批量产出最终文档。整个过程不需要安装商业套件，也不用报什么低代码平台的培训班，用我在某公司数据部门带团队这几年攒下的经验，配合开源项目就能搭出一套稳定的批量文档生成流水线。

这篇文章不会只贴一串代码了事，我会把环境准备、Excel和Word的设计规范、JSON中间层的用途、脚本的完整逻辑、还有我实际踩过的坑，全部拆开揉碎讲清楚。比如为什么要在Excel后面加一个JSON层而不是直接读Excel去填Word、模板里占位符怎么命名才能让同事接手时不发疯、Docx库处理表格循环时有哪些隐藏的坑。这些东西基本是我在日常工作中被真实项目反复捶打之后才领会的细节，至少可以帮你省掉两个月的摸索时间。

1. 内容整体设计与思路拆解

1.1 先看清这套方案要解决的核心问题

先说个我经手的真实例子。某公司综合管理部每周要给几十个项目经理发送任务考核表，内容包括项目名称、负责人、各项反馈意见，以及一段针对项目经理的专业评价。以前同事的做法是：Excel里维护数据，每季度根据考核结果，在Word里挨个新建文档，然后把Excel里的数值一项项往模板里粘贴。高峰期一天干了六个小时，手都酸了，而且经常出现考核金额写错、部门名称前后不一致这种低级错误。

这个场景非常有代表性。凡是你发现以下现象，就说明值得搭建一套自动生成文档的流水线：

• Excel已经维护了大量的结构化数据，但最终对外交付需要通过Word文档呈现
• 生成文档的流程高度重复，每周、每月、每季度都要执行，且数量不小
• 文档输出有固定的模板和格式要求，但数据内容在持续更新
• 参与数据维护的人不一定懂编程，他们只会填Excel表

1.2 为什么选Excel做数据入口，JSON做中间层，Word模板做输出

很多刚开始接触这块的同学会问：“为什么不直接用办公套件的邮件合并功能，或者商业报表工具里的Word导出功能？”这个问题的答案就在于约束条件和长期维护成本。

邮件合并功能确实能解决一部分问题，但它的短板也明显：处理复杂循环（比如一张合同里要列出不定数量的明细项）时非常乏力，而且每次数据范围变了都要重新调整邮件合并的几个步骤。商业报表工具的Word导出做得成熟，但往往价格不菲，还可能把团队绑定在特定平台上。

所以我选的组合是：Excel作为数据源，因为它最普及，团队里任何同事都会操作；JSON作为中间层，因为它结构清晰、层次分明，可以把Excel里的“平铺”数据重新组织成“嵌套”结构，也方便调试；Word模板用一套基于docxtpl的开源方案，直接在Word里写占位符即可，对非技术同事的入门门槛低。

这套方案的核心思路是：让整个流程像流水线一样，每一道工序只干一件事，把变化的部分（数据）和不变的部分（模板版式）彻底解耦。当模板版式调整时，只需要改Word模板文件；当数据更新时，只需要刷新Excel表；脚本本身几乎不用动。

2. 工具选型解析与运行环境准备

2.1 技术组件的选型：为什么是docxtpl而不是直接操作XML

Python生态里操作Word文档的方案不少，但真正适合批量模板生成场景的，我强烈推荐docxtpl。

• 它基于python-docx封装，但是引入了docxtpl的模板渲染机制，允许在Word模板中直接写占位符和简单的循环语法。
• 对模板制作人员很友好：不需要写一行Python代码，只要会用Word就能做模板。
• 循环、条件判断、图片占位这些复杂需求它也能处理，这里有相应的用法。

相比之下，直接操作XML的方案太底层、学习成本太高，用原生python-docx往文档里逐段追加内容又相当于放弃了模板设计。docxtpl站在二者之间，把“模板制作”和“业务逻辑”分得很开，特别适合团队协作的办公自动化场景。

2.2 Python环境与依赖库安装

环境准备本身不难，但有个细节值得注意：docxtpl依赖的库比较多，建议新建一个虚拟环境，避免把本机的Python环境搅浑。

创建并激活虚拟环境：

python -m venv sheet2doc_env # Windows: sheet2doc_env\Scripts\activate # macOS/Linux: source sheet2doc_env/bin/activate

安装核心依赖库：

pip install docxtpl pandas openpyxl

三个库的分工很清晰：pandas和openpyxl负责读取Excel数据，docxtpl负责渲染Word模板。需要处理图片的话，还要额外安装Pillow库。

pip install Pillow

我建议把用到的依赖写进requirements.txt文件，方便后续在别的电脑上快速复现，也省得哪天重装系统后忘记当时装了什么。

3. 数据源与模板的设计规范

3.1 Excel数据源的设计：一张好表胜过十次调试

Excel文件是整个流水线的源头。这里的Table怎么设计，直接影响后续JSON的质量和脚本写的顺手程度。我自己的经验是，在项目启动前就要定好一套命名规范和字段约定。

以批量生成“项目任务考核表”为例，Excel工作表（Sheet）规划大体如下：

这里有几个大家容易忽视的细节：

• 表头不要带合并单元格、不要同一列里塞两种类型的数据。Excel对不太规范的表格容忍度很高，但程序对数据类型非常敏感。某列如果大部分是数字，偶尔有几个单元格里不小心输入了“92.5分”，程序读取后类型就出问题了。
• 多行文本不要用一个单元格里硬塞十几句，建议用单元格内换行（Alt+Enter），读取时再按换行符拆分成列表。
• 日期类字段建议在Excel里设置成“日期”格式，Python读取后统一转成字符串再传给JSON，避免按天算的时区偏移问题——这一点很多人吃过亏。

3.2 Word模板设计与占位符命名规范

这个环节是整个方案的重中之重。模板设计得好不好，直接影响最终文档的观感和维护成本。

在Word里制作模板时，先画出完整的定制版式，然后把需要替换的地方替换成docxtpl约定的占位符，格式是双大括号加变量名。

例如：

项目名称：{{ project_name }} 项目经理：{{ manager_name }} 考核总分：{{ total_score }} 考核等级：{{ grade }}

如果模板里要输出一段多行文本，比如“整改反馈”下面要逐条列出反馈意见，可以在模板里用一段循环语法：

{% for opinion in feedback_list %} - {{ opinion }} {% endfor %}

docxtpl里的循环语法和Jinja2模板语法是一致的。对于没有编程基础的同事来说，记住这几条语法就够了。命名方面我有一条比较严格的规范：占位符一律用小写下划线命名，并且字段名必须和Excel表头保持一致，最多允许加前缀区分数据源。

举例：

• Excel表头是“项目名称”，那占位符就叫project_name
• Excel表头是“项目经理”，那占位符就叫manager_name

这样命名规则一确定，后续谁维护都知道哪个占位符对应哪个Excel字段。我最怕见到模板里出现tmp1、valueA这类毫无含义的变量名，这样的模板三个月后连写的人自己都看不懂。

3.3 JSON中间层：为什么值得为它单独写一段逻辑

很多自动化方案会直接从Excel读数据然后填Word模板，省掉JSON这一步。但我在实践中坚持引入JSON中间层，原因有四个：

• Excel里的数据是“平铺”的，每一行是一条记录，但Word模板往往需要“嵌套”的数据结构。比如一个员工要生成一份培训记录表，表头是员工基本信息，正文是多条培训明细，明细的数量不固定。如果用pandas直接读Excel，要做很多数据重组的逻辑，操作起来非常绕。但如果在JSON层做一次手工加工，把明细列表归纳到员工对象下面，模板渲染就非常顺了。
• JSON可以被反复调试，而且查看非常方便。脚本把Excel转成JSON后再人工检查一遍，往往能提前发现脏数据。
• JSON是纯文本格式，可以比较方便地做接口对接。后续如果Excel被改成前端表单或API接口，只要生成同样的JSON，脚本就不用动。
• 如果单个Excel里面有多个Sheet，可以在JSON层自然形成对象列表，结构一清二楚。

4. 实操过程与核心环节实现

4.1 从Excel到JSON：写出你自己的数据清洗函数

这一环节的输入是Excel表格，输出是一个结构清晰的JSON列表，列表中每个元素对应一份将来要生成的Word文档所需的数据。

下面是我常用的一段核心代码，代码不长但关键细节很多：

import pandas as pd import json from datetime import datetime def excel_to_json(excel_path, sheet_name): # 读取Excel，dtype始终保持字符串，后续再针对性转换 df = pd.read_excel(excel_path, sheet_name=sheet_name, dtype=str) # 去掉完全空行 df = df.dropna(how='all') # 去掉前后空格，避免出现' 张某某 '这种脏数据 df.columns = [col.strip() for col in df.columns] records = [] for _, row in df.iterrows(): # 跳过没有单据编号的行 if not row.get('单据编号') or str(row['单据编号']).strip() == '': continue # 处理多行文本，按换行符拆分 feedback_raw = row.get('整改反馈', '') if isinstance(feedback_raw, str): feedback_list = [item.strip() for item in feedback_raw.split('\n') if item.strip()] else: feedback_list = [] # 日期统一格式 date_raw = row.get('下发日期', '') if isinstance(date_raw, str) and date_raw.strip(): try: date_str = datetime.strptime(date_raw.strip(), '%Y-%m-%d').strftime('%Y年%m月%d日') except ValueError: date_str = date_raw.strip() else: date_str = '' record = { 'doc_no': row.get('单据编号', '').strip(), 'project_name': row.get('项目名称', '').strip(), 'manager_name': row.get('项目经理', '').strip(), 'department': row.get('汇报部门', '').strip(), 'total_score': row.get('考核总分', '').strip(), 'grade': row.get('考核等级', '').strip(), 'feedback_list': feedback_list, 'date_str': date_str } records.append(record) return records records = excel_to_json('考核数据.xlsx', '月度考核') with open('考核数据.json', 'w', encoding='utf-8') as f: json.dump(records, f, ensure_ascii=False, indent=2)

这段代码里面有几个我特别想强调的细节：

• dtype=str强制让pandas把所有单元格按文本读取，避免身份证号、单据编号这类长数字被弄成科学计数法。这是清洗Excel数据时很基础但也极常见的一个坑。
• 日期处理后转成“2025年01月20日”这种中文格式，是为了在Word里直接显示成正式文书的风格，不用再单独设置数字格式。
• 多行文本拆成列表之后，模板渲染时用{% for opinion in feedback_list %}循环输出，每条意见前可以带一个圆点或编号，比一整段文本美观得多。

4.2 从JSON到Word：模板渲染与文件批量命名

数据准备好之后，就是docxtpl出场的时候了。先看核心渲染函数的写法：

from docxtpl import DocxTemplate def render_document(template_path, output_path, context): doc = DocxTemplate(template_path) doc.render(context) doc.save(output_path) return output_path

整个渲染其实就三步：加载模板文件、把数据塞到context变量里、渲染后另存为新文件。

更完整一点的调度逻辑，是把一批任务用Excel生成的JSON驱动循环处理：

import json with open('考核数据.json', 'r', encoding='utf-8') as f: records = json.load(f) template_file = '考核通报模板.docx' for rec in records: context = { 'project_name': rec['project_name'], 'manager_name': rec['manager_name'], 'department': rec['department'], 'total_score': rec['total_score'], 'grade': rec['grade'], 'feedback_list': rec['feedback_list'], 'date_str': rec['date_str'], 'doc_no': rec['doc_no'] } output_name = f"{rec['doc_no']}_{rec['project_name']}.docx" render_document(template_file, output_name, context)

这就是整个自动化生成的核心循环。Excel里有几行有效数据，就会生成几个Word文档。文档命名规则按“单据编号_项目名称.docx”拼接，非常便于后续归档和检索。

我的习惯是在脚本里增加一个输出目录判断，确保每次生成的文件都集中放在同一个文件夹里，避免把生成的文档和模板搞混：

import os output_dir = 'output' if not os.path.exists(output_dir): os.makedirs(output_dir) output_path = os.path.join(output_dir, f"{rec['doc_no']}_{rec['project_name']}.docx") render_document(template_file, output_path, context)

4.3 模板里表格循环与图片占位的处理

Word模板如果只需要替换几段普通文字，docxtpl处理起来很简单，但一旦模板里出现表格，解法就完全不同了。

我遇到过很多次这种需求：表格里每一行代表项目团队成员、培训记录明细、产品清单，行数不确定。docxtpl支持把模板中表格的一行视作循环模板，在行首用{%tr 循环变量 %}标记循环开始，在行尾用{%tr endfor %}标记循环结束。

假设考核模板里有个表格，列是成员姓名、角色、所属小组：

那么Word模板里对应的表格第一行要写成：

{%tr for member in member_list %} | {{ tr.member_name }} | {{ tr.role }} | {{ tr.group_name }} | {%tr endfor %}

在docxtpl的文档中，循环表格使用的就是{%tr ... %}语法。传数据时，context里给一个member_list列表，列表元素是包含member_name、role、group_name的字典。渲染时，docxtpl会自动复制那一行模板并填充数据。

图片占位也是实际需求里比较常见的。docxtpl里塞图片需要先把图片转成字节流，再传给模板中的{{ image_var }}变量：

from docxtpl import InlineImage from docx.shared import Inches # 假设有一张签名或盖章图片 img_path = 'signature.png' img_stream = InlineImage(doc, img_path, width=Inches(1.5)) context = { 'signature_img': img_stream } doc.render(context)

这个InboxImage对象只能调用一次，如果同一个context要渲染多份文档，务必在每次渲染时重新创建图片对象，否则第二份文档拿到的图片引用可能会处理异常。

5. 常见问题与排查技巧实录

5.1 编码与中文乱码问题的集中排查

中文环境下跑这类脚本，乱码问题可以说是排在所有问题清单第一位的。大部分情况下不是Python本身编码错误，而是读取阶段数据类型或编码处理不当导致的。

• 如果Excel读取后中文正常，但生成的Word里中文乱码，排查优先级最高的是模板文件是否设置正确。确保Word模板保存时编码格式正常，不要使用带特殊保护的模板文件。
• 打开生成后的Word文档时提示“文件中包含损坏的内容”，多半是模板中嵌套过复杂样式，或占位符被写到文本域（Content Control）里。遇到这种情况，我建议把模板中内容删除后重新插入普通文本占位符，不要保留原文档里的智能控件。
• 在JSON文件里检查中文是否正常时，注意打开文件时要指定UTF-8编码，很多文本编辑器默认会用本地编码打开UTF-8文件，看似乱码其实数据本身没问题。

我在团队里内部规定：所有Excel模板统一格式，首行表头不许合并单元格，字段名一律用简体中文；JSON导出时强制ensure_ascii=False；脚本文件头部声明编码方式是UTF-8。这些规定看起来琐碎，但真的能省掉大量排查时间。

5.2 模板渲染后Word样式错乱的对策

docxtpl一个让人头大的问题是：渲染完成后的文档，某些段落字体或段落间距会发生变化。出现这个问题的根源在于模板里的占位符嵌在哪里，样式就跟随那个位置的段落设置。

经验法则有三个：

• 如果发现模板某段文字用了仿宋或黑体，但生成后字体变了，检查Word模板中占位符所在段落本身设置的字体是否被“正文样式”污染。把光标点在占位符那一行，重新设置一遍字体、字号、行距，再保存模板。
• 不要在模板里用“自动更新”的文档主题字体。不同版本或不同机器打开模板时，主题字体一变，渲染结果也跟着变。
• 中文正文想要统一的仿宋GB2312或宋体，建议在模板中用样式管理器把“正文”样式直接修改成最终想要的格式，这样占位符旁的段落样式会自动继承。

另外，如果已经生成完才发现某处段落样式不对，不要手工逐份改，正确的做法是回到模板改一遍，然后重新执行脚本批量生成。这是自动化方案最舒服的地方——改一次模板，所有文档统一更新。

5.3 表格循环与嵌套列表的坑

docxtpl的循环语法对简单列表很友好，但一旦表格里还有嵌套数据就有讲究了。比如一个项目可能需要输出多个阶段的任务明细，每个阶段下又有多个反馈意见，这种两层嵌套结构并不适合在Word模板里硬生生用循环处理。

我自己的办法是：在Excel的数据源阶段就把嵌套结构拉平。比如一列写阶段名称，另一列写该阶段的反馈意见，循环时先按阶段分组，在JSON里形成嵌套字典列表。这样既能保持Word模板简洁，又不会因为多层循环把模板渲染搞崩。

嵌套循环或复杂控制流在docxtpl的表格模板里相当容易出现空格错位和空行问题，正确的底层逻辑其实是：模板越简单越不容易出错。能在Excel阶段处理完的整理类工作，就不要把逻辑闭环交给模板函数来操心。

5.4 动态文件名与重复运行的安全策略

自动生成脚本跑第一次很顺利，第二次重复执行时会发现一个问题：生成的文档被覆盖了。很多场景下这没问题，但如果你希望每个批次的历史文档都保留，就不能让文件名固定不变。

我常用的做法是：在文件名后面追加当前时间戳：

from datetime import datetime timestamp = datetime.now().strftime('%Y%m%d_%H%M%S') output_name = f"{rec['doc_no']}_{rec['project_name']}_{timestamp}.docx"

这样每次执行脚本生成的都是新文件，可以保留历史版本，也方便归档对比。如果是定期的“最新版替换旧版”场景，则不加时间戳，保持文件名不变，覆盖即可。

另外我强烈建议在脚本开头加一段备份模板的逻辑，把模板文件拷贝到template_backup目录。因为docxtpl渲染时不会修改原模板文件，但防不住你手滑用脚本误覆盖模板文件路径。备份成本极低，但真的能救命。

5.5 大文件批量生成时的性能问题

当数据量达到几百份文档时，脚本执行时间会长到让人怀疑程序卡死。我实测下来，一份常规篇幅的Word模板渲染大约需要0.5到1.5秒，如果脚本里对每份文档都加载一次模板，500份文档可能要跑十几分钟。

优化策略很明确：一次性加载模板对象，循环内复用同一个DocxTemplate实例。不过这里需要注意，docxtpl的同一模板对象多次render时，如果context中图片对象没有重新创建，会影响后续渲染结果。图片对象必须在每次渲染时重建，文字类数据则可以安全地复用模板对象。

另外一个容易被忽视的细节是：循环里反复打开关闭输入输出文件流会增加额外开销，尽量把文件读写操作放在确认数据合法后一次性执行。

6. 这套方案的延伸价值与后续扩展

6.1 从批量生成到定期自动执行

脚本跑顺之后，可以考虑做一个简单的批处理文件或系统计划任务，让整个流程在每周或每月的固定时间自动运行。比如在Windows计划任务里设置一个任务，每周五下午六点执行一次Python脚本，自动从网盘或共享目录拉取Excel、渲染模板、归档到指定文件夹。

这样做之后，团队实际上一只手都不用动，整套文档生成工作就自动完成了。我在实际推广这套方案时，部门的同事只需要每周上传更新Excel，其他环节全部自动化。

6.2 与Web表单、API对接的可能性

这套方案还有一个我特别看好的扩展方向：JSON中间层可以天然替换成API接口或Web表单提交的数据。

举例来说，假如以后想要让项目组成员在线填写考核数据，就不需要再维护Excel文件了，后端接收表单提交后生成同样的JSON结构，接下来调用render函数生成文档，整个链路几乎不用改。这让“Sheet to Doc”有了向“Form to Doc”甚至“API to Doc”演进的可能，扩展成本低得惊人。

6.3 错误隔离与审计留痕

批量生成过程中一旦某个数据有问题（比如某个占位符缺失、某个字段为空），脚本通常会直接报错终止。线上跑的时候这种情况是不能接受的，所以我会在循环里做错误捕获：

for rec in records: try: render_document(template_file, context, output_path) except Exception as e: print(f"处理单号 {rec['doc_no']} 失败: {e}") with open('error_log.txt', 'a', encoding='utf-8') as log: log.write(f"{rec['doc_no']} - {str(e)}\n")

这样即使某一条数据异常，也不会拖累整个批次。错误日志会记录下来，事后统一排查即可。这个看似简单的try-except，在实际项目中帮我避免过好几次“早上起来发现昨晚的批次白跑了”的尴尬。

7. 写在实际操作之后的真心话

这套“Sheet to Doc”方案我在不同项目中迭代了好几轮，从最初只处理纯文字替换，到后来支持表格循环、图片签名、自动归档，稳定性越来越高，同事的满意度也上来了。

我觉得它最朴素的价值并不是“自动化”这三个字，而是把职场里大量重复、枯燥、容易出错的文书工作，变成了一套可维护、可解释、可交接的规则系统。Excel表谁来都能填，Word模板谁来都能改，JSON和脚本是中间那根别人看不见但非常可靠的数据管道。

如果你正在被批量文档生成折磨，或者想给团队搭一套自动化文书流水线，我会建议你从一张规模很小的Excel表和一份简单的Word模板入手，先跑通一两个真实场景，再慢慢扩展。用不了几次迭代，你就会发现原来一群人半天的工作量，现在只要喝杯咖啡的时间就完成了。