1. 为什么办公文档自动化是绕不开的一课做 Python 自动化的人早晚会撞上 Office 文档这堵墙。你可能一开始只是想批量改几个 Word 里的日期或者从一堆 Excel 里把某几列数据抠出来汇总结果搜着搜着就掉进了python-docx、openpyxl、xlrd、pandas这一堆库的坑里光选型就耗掉半天。更别提那些看起来能跑、换个文件就报错的诡异情况——合并单元格读出来是 None、Word 里的表格跨页后行数对不上、生成的文档打开提示内容有问题需要修复。这篇是 Python 系列的第一篇专门聊创建和解析 Office 文档这件事。所谓创建就是让程序从零生成一份 Word、Excel 或 PowerPoint所谓解析就是把已有的文档拆开把里面的文字、表格、样式、公式读出来变成程序能处理的数据。这两件事合起来基本覆盖了日常办公自动化的八成场景批量生成合同、自动填报表、从报告里提取关键指标、把数据表转成图文并茂的汇报材料。适合谁看如果你已经会写基本的 Python 循环和函数但一碰到.docx、.xlsx就不知道从哪下手这篇就是给你准备的。我会把选型逻辑、核心 API 的用法、以及那些文档里不会写的踩坑经验都摊开讲。全程用从业者之间交流的口吻不绕弯子能直接抄的代码我都给出来。先说一个反直觉的结论处理 Office 文档最难的从来不是写代码而是理解文档本身的格式规范。.docx和.xlsx本质上都是 ZIP 压缩包里面装着一堆 XML。你用的库只是帮你把这层 XML 包装成了 Python 对象。理解这一点后面遇到各种莫名其妙的问题时你就能顺着 XML 结构去排查而不是对着报错干瞪眼。2. 选型之前先搞清楚你到底在跟什么格式打交道2.1 老格式和新格式是两套完全不同的东西很多人栽的第一个跟头就是没分清.doc和.docx、.xls和.xlsx。这两组看起来只差一个字母底层却是天壤之别。.doc、.xls、.ppt是微软早期的二进制格式文件内部是一段紧凑的二进制流没有公开的、友好的解析规范。Python 想读它们基本只能靠xlrd仅限 xls、pywin32调用本机 Office 组件这类方式跨平台性差还经常因为环境没装 Office 而失败。.docx、.xlsx、.pptx是 2007 年之后基于 Office Open XML 规范的格式本质是 ZIP 包加 XML。你可以直接把一个.docx的后缀改成.zip解压后能看到word/document.xml、word/styles.xml这些文件。这种开放性让第三方库可以纯 Python 解析不依赖 Office 软件本身。所以选型的第一条铁律新项目一律只支持新格式。如果业务方丢给你一堆.doc正确做法是先批量转成.docx再处理而不是硬着头皮去啃二进制。转换可以用 LibreOffice 的命令行模式批量做这个后面会讲。2.2 三大件对应的主力库文档类型创建解析说明Word (.docx)python-docxpython-docx读写一体API 直观Excel (.xlsx)openpyxlopenpyxl读写一体支持公式和样式Excel 数据分析pandaspandas适合纯数据场景不碰样式PowerPoint (.pptx)python-pptxpython-pptx读写一体老格式 (.doc/.xls)不推荐xlrd(仅xls)建议先转换这里有个常见的误区很多人一上来就用 pandas 读 Excel觉得一行pd.read_excel()就搞定何必学 openpyxl。但 pandas 的定位是数据分析它读 Excel 时会把所有内容当成数据表样式、合并单元格、公式、批注这些信息全部丢掉。如果你只是想把表格数据拿来做统计pandas 确实快但如果你要保留格式、要写回带样式的报表、要处理合并单元格就必须用 openpyxl。我的经验是数据进 pandas格式进 openpyxl。两者可以配合用 openpyxl 读带格式的原始文件把纯数据部分转成 DataFrame 做计算算完再用 openpyxl 写回带样式的模板。2.3 安装与环境准备pip install python-docx openpyxl python-pptx pandas装完之后建议先跑一个最小验证确认库能正常导入import docx import openpyxl import pptx print(docx.__version__ if hasattr(docx, __version__) else docx ok) print(openpyxl.__version__) print(pptx.__version__)注意python-docx的包名是python-docx但导入时写import docxpython-pptx导入时写import pptx。这个命名不一致坑过不少人装的时候别装成docx那个同名的老包那个是另一个项目。3. Word 文档从生成一份合同到拆解一份报告3.1 用 python-docx 从零生成文档先看创建。假设你要批量生成一批通知书每份的姓名、日期、金额不同但格式完全一样。最朴素的做法是准备一个模板然后替换占位符。但 python-docx 本身没有查找替换这种高级功能你得自己遍历段落和表格里的 run。先理解 python-docx 的对象模型一个 Document 包含若干 Paragraph段落每个 Paragraph 包含若干 Run文本片段。Run 是样式的最小单位同一段里不同字体、不同加粗的文本会被拆成多个 Run。这个模型很关键因为替换文字时如果直接改 Paragraph.text会把整段的样式全冲掉。from docx import Document from docx.shared import Pt, RGBColor from docx.enum.text import WD_ALIGN_PARAGRAPH doc Document() # 添加标题 title doc.add_heading(项目结项通知书, level1) title.alignment WD_ALIGN_PARAGRAPH.CENTER # 添加正文段落 p doc.add_paragraph(兹有) run p.add_run(张三) run.bold True run.font.color.rgb RGBColor(0xC0, 0x00, 0x00) p.add_run(同志您参与的项目已通过验收。) # 添加表格 table doc.add_table(rows3, cols2) table.style Table Grid table.cell(0, 0).text 项目名称 table.cell(0, 1).text 某跨平台系统 table.cell(1, 0).text 结项日期 table.cell(1, 1).text 2024-06-01 table.cell(2, 0).text 负责人 table.cell(2, 1).text 张三 doc.save(notice.docx)这段代码里几个点值得展开。add_heading用的是内置样式level1 对应标题 1。如果你想要自定义字体得去改样式对象而不是直接设 run 的字体——因为标题样式会覆盖 run 级别的设置。table.style Table Grid是给表格加边框不加的话默认是无框线打印出来一片空白。3.2 模板替换为什么直接改 text 会翻车批量生成场景下更实用的做法是准备一个.docx模板里面写好{{name}}、{{date}}这样的占位符然后程序读模板、替换、另存。但前面说了python-docx 没有内置替换。网上流传的写法是遍历doc.paragraphs对每个paragraph.text做replace然后重新赋值。这个写法有个致命问题它会把段落里所有 Run 的样式合并成一个。正确的做法是遍历 Run在 Run 级别替换def replace_in_paragraph(paragraph, mapping): for run in paragraph.runs: for key, value in mapping.items(): if key in run.text: run.text run.text.replace(key, value)但这里还有个坑占位符可能被拆到多个 Run 里。比如{{name}}在 Word 里可能因为编辑历史被拆成{{、name、}}三个 Run。这时候单个 Run 里根本找不到完整的占位符。解决办法有两种一是替换前先把段落里所有 Run 的文本合并判断如果占位符跨 Run就重建整个段落二是用更专业的库如docxtpl它基于 jinja2 模板引擎专门解决这个问题。我的建议是简单场景用 python-docx 手动替换复杂模板直接上 docxtpl。docxtpl 的用法是doc.render(context)context 是个字典模板里写{{ name }}还支持循环和条件判断做批量合同、证书这类场景非常省事。3.3 解析 Word表格和段落要分开处理解析比创建更容易踩坑。一个 Word 文档里文字可能出现在三个地方普通段落、表格单元格、页眉页脚。很多人只遍历doc.paragraphs结果发现表格里的内容全丢了。def extract_all_text(doc): texts [] # 普通段落 for p in doc.paragraphs: if p.text.strip(): texts.append(p.text) # 表格 for table in doc.tables: for row in table.rows: cells [cell.text.strip() for cell in row.cells] texts.append( | .join(cells)) return texts这里有个隐蔽的坑合并单元格会导致同一段文字被重复读取。比如一个横向合并的单元格row.cells会返回多个指向同一个底层单元格的对象你读到的文字就重复了。判断方法是比较 cell 的_tc属性底层 XML 元素是否相同seen set() for cell in row.cells: if id(cell._tc) not in seen: seen.add(id(cell._tc)) # 处理这个 cell另一个坑是跨页表格的行数。Word 里一个表格如果跨页python-docx 读出来仍然是一个 table 对象行数是完整的这点不用担心。但如果文档里有两个独立的表格被排版成看起来连在一起那就是两个 table需要分别处理。3.4 页眉页脚和文本框容易被忽略的角落页眉页脚的内容不在doc.paragraphs里要单独访问for section in doc.sections: header section.header for p in header.paragraphs: print(p.text) footer section.footer for p in footer.paragraphs: print(p.text)文本框Text Box更麻烦python-docx 没有直接 API得深入到 XML 层面去遍历w:txbxContent节点。如果业务文档里大量用文本框排版解析起来会非常痛苦。我的经验是如果解析需求涉及文本框先评估能不能让业务方改用普通段落实在不行再上 XML 解析。4. Excel 文档数据、公式、样式三条线要分开走4.1 openpyxl 的读写基本盘Excel 是办公自动化里出现频率最高的。openpyxl 的核心对象是 Workbook、Worksheet、Cell。读一个文件import openpyxl wb openpyxl.load_workbook(data.xlsx, data_onlyTrue) ws wb[Sheet1] for row in ws.iter_rows(min_row2, values_onlyTrue): name, age, score row print(name, age, score)这里data_onlyTrue是个关键参数。Excel 单元格里存的可能是公式比如A1B1。默认情况下 openpyxl 读出来的是公式字符串本身设了data_onlyTrue它读的是公式上一次被 Excel 计算后缓存的结果。注意这个缓存值只有在文件被 Excel 打开并保存过之后才存在。如果文件是程序生成的、从没被 Excel 打开过data_onlyTrue读出来会是 None。这个坑非常隐蔽很多人卡在这里半天找不到原因。写文件wb openpyxl.Workbook() ws wb.active ws.title 汇总 ws.append([姓名, 部门, 金额]) ws.append([张三, 研发, 12000]) ws[D1] SUM(C2:C2) wb.save(output.xlsx)ws.append()按行追加适合从列表批量写入。写公式直接写字符串但注意公式里的函数名和参数分隔符要符合 Excel 规范中文版 Excel 用逗号分隔参数这个和英文版一致不用担心。4.2 样式、合并单元格与列宽生成报表时样式很重要。openpyxl 的样式通过Font、PatternFill、Border、Alignment这些对象组合from openpyxl.styles import Font, PatternFill, Alignment, Border, Side header_font Font(name微软雅黑, size11, boldTrue, colorFFFFFF) header_fill PatternFill(solid, fgColor4472C4) center Alignment(horizontalcenter, verticalcenter) for cell in ws[1]: cell.font header_font cell.fill header_fill cell.alignment center ws.merge_cells(A1:C1) ws.column_dimensions[A].width 15合并单元格要注意合并后只有左上角那个单元格能写值其他单元格的值会被清空。读取时合并区域的非左上角单元格返回 None。如果你要遍历读取得先判断单元格是否在合并区域内或者用ws.merged_cells.ranges拿到所有合并区域自己映射回左上角。4.3 大文件处理为什么你的脚本越跑越慢openpyxl 有个性能问题它默认把整个工作簿加载到内存几万行的表还能扛几十万行就会吃光内存。这时候有两个选择。一是用read_onlyTrue模式它用流式读取内存占用小但只能顺序读不能随机访问单元格也不能修改wb openpyxl.load_workbook(big.xlsx, read_onlyTrue) ws wb.active for row in ws.iter_rows(values_onlyTrue): process(row) wb.close()二是写大文件时用write_onlyTrue配合ws.append()逐行写避免在内存里维护完整的工作表对象wb openpyxl.Workbook(write_onlyTrue) ws wb.create_sheet() for record in data_stream: ws.append(record) wb.save(big_output.xlsx)实测下来写 50 万行数据普通模式内存能飙到 2GB 以上write_only 模式稳定在几百 MB。这个差距在处理日志导出、数据备份这类场景里是决定性的。4.4 pandas 和 openpyxl 怎么配合前面说过纯数据分析用 pandas 更顺手。典型流程是用 openpyxl 读带格式的原始表把数据区转成 DataFrame 做清洗和计算再用 openpyxl 把结果写回带样式的模板。import pandas as pd import openpyxl # 读数据 df pd.read_excel(raw.xlsx, sheet_name明细, skiprows2) df[金额] df[数量] * df[单价] summary df.groupby(部门)[金额].sum().reset_index() # 写回带样式的模板 wb openpyxl.load_workbook(template.xlsx) ws wb[汇总] for i, row in summary.iterrows(): ws.cell(rowi2, column1, valuerow[部门]) ws.cell(rowi2, column2, valuerow[金额]) wb.save(report.xlsx)skiprows2是因为原始表前两行是标题和说明不是数据。这种参数要根据实际文件调整没有通用值。pandas 读 Excel 时如果表头不在第一行一定要用header和skiprows配合否则列名会错位。5. 那些文档里不会写的踩坑实录5.1 文件被占用导致保存失败最常见的报错之一PermissionError: [Errno 13] Permission denied。原因几乎都是目标文件正在被 Excel 或 Word 打开。Windows 下 Office 会锁定文件程序写不进去。解决办法不是加 try-except 硬扛而是从流程上避免生成的文件名带时间戳或者先写到临时文件再移动。import os import tempfile import shutil tmp tempfile.NamedTemporaryFile(suffix.xlsx, deleteFalse) wb.save(tmp.name) tmp.close() shutil.move(tmp.name, output.xlsx)这样即使 output.xlsx 被占用也只是最后一步 move 失败不会丢数据。5.2 中文乱码与字体问题生成的文档里中文显示成方框通常是字体没设对。python-docx 默认用 Calibri这个字体不含中文字形。解决办法是显式设置中文字体from docx.oxml.ns import qn run p.add_run(中文内容) run.font.name 微软雅黑 run._element.rPr.rFonts.set(qn(w:eastAsia), 微软雅黑)注意那个w:eastAsia的设置只设font.name对中文不生效必须同时设 eastAsia 属性。这是 python-docx 的一个历史遗留问题官方文档里提得很少但实际项目里几乎必踩。5.3 日期格式的坑Excel 里的日期本质是个浮点数整数部分是天数小数部分是时间。openpyxl 读出来可能是 datetime 对象也可能是数字取决于单元格格式。如果读出来是数字用openpyxl.utils.datetime.from_excel()转换。写日期时直接写 datetime 对象openpyxl 会自动处理格式如果写字符串Excel 会当成文本后续没法做日期计算。5.4 批量转换老格式前面提到.doc转.docx用 LibreOffice 命令行最省事soffice --headless --convert-to docx --outdir ./converted ./old_files/*.doc这个命令在 Linux 和 Windows 都能用Windows 下是soffice.exe。转换是批量的但要注意 LibreOffice 的排版引擎和微软 Office 有细微差异复杂排版的文档转换后可能错位。所以转换后最好抽样检查几份。6. 把创建和解析串成一条流水线单点操作会了之后真正的价值在于把创建和解析串起来形成自动化流水线。举个典型场景每月从多个部门收集 Excel 报表汇总后生成一份 Word 分析报告。流程拆解先用 openpyxl 遍历各部门的 Excel读取数据并校验比如检查必填列是否为空、数值是否在合理范围把校验通过的数据汇总到一个 DataFrame做统计计算然后用 python-docx 打开报告模板把统计结果填入对应的占位符和表格最后保存并归档。这个流水线里校验环节最容易被忽略但最重要。我见过太多脚本因为某个部门的表多了一行空行、或者列顺序变了就直接崩溃。健壮的做法是读取时用列名定位而不是列号遇到缺失列记录警告并跳过该文件而不是让整个流程挂掉。required_cols [部门, 项目, 金额] for file in files: try: df pd.read_excel(file) missing [c for c in required_cols if c not in df.columns] if missing: log.warning(f{file} 缺少列: {missing}跳过) continue # 继续处理 except Exception as e: log.error(f{file} 读取失败: {e}) continue这种跳过坏数据、记录日志、继续处理的模式在生产环境里比一遇错就抛异常实用得多。因为批量任务里个别文件有问题不应该影响整体。再补一个经验生成文档时保留中间产物。比如汇总的 DataFrame 存一份 CSV填充后的 Word 存一份草稿这样出问题时能快速定位是哪一步错了而不是从头重跑。这个习惯在调试阶段能省大量时间。7. 几个提升效率的实用技巧第一个技巧是关于路径处理的。Windows 下路径用反斜杠Linux 用正斜杠写死任何一种都会在另一个平台翻车。统一用pathlibfrom pathlib import Path base Path(data) for f in base.glob(*.xlsx): print(f.name, f.stem, f.suffix)glob支持通配符stem是不带后缀的文件名这些比字符串拼接靠谱得多。第二个技巧是给文档操作加日志。批量处理几十上百个文件时出问题在所难免有日志才能快速定位。用标准库的 logging配置成同时输出到控制台和文件import logging logging.basicConfig( levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, handlers[logging.FileHandler(process.log), logging.StreamHandler()] )第三个技巧是处理超大批量时的进度反馈。用tqdm包一层循环能直观看到进度和预估剩余时间from tqdm import tqdm for f in tqdm(files, desc处理中): process(f)第四个技巧也是我个人踩坑最多的一条永远不要相信输入文件的格式是规范的。业务方给你的 Excel可能有隐藏行、有筛选状态、有冻结窗格、有数据验证、有批注这些在 openpyxl 里读出来都是额外的属性。如果你的脚本只关心数据读的时候用values_onlyTrue忽略格式如果关心格式就要做好遇到各种意外属性的准备。最稳妥的做法是先用一个小脚本把文件的结构打印出来看看再写正式处理逻辑。wb openpyxl.load_workbook(unknown.xlsx) for ws in wb.worksheets: print(fSheet: {ws.title}, 维度: {ws.dimensions}, 最大行: {ws.max_row}, 最大列: {ws.max_column}) print(f合并区域: {list(ws.merged_cells.ranges)}) print(f冻结窗格: {ws.freeze_panes})这几行打印出来的信息能帮你快速判断这个文件干净不干净值不值得直接上自动化还是需要先做一轮清洗。Office 文档自动化这件事库的 API 只是表层真正决定成败的是你对文档格式的理解和对异常情况的预判。把上面这些坑都趟过一遍之后你会发现大部分问题都有规律可循无非是格式差异、样式覆盖、文件占用这几类。下一篇我会聊 PDF 和图片的处理那又是另一套完全不同的逻辑了。
1. 为什么办公文档自动化是绕不开的一课做 Python 自动化的人早晚会撞上 Office 文档这堵墙。你可能一开始只是想批量改几个 Word 里的日期或者从一堆 Excel 里把某几列数据抠出来汇总结果搜着搜着就掉进了python-docx、openpyxl、xlrd、pandas这一堆库的坑里光选型就耗掉半天。更别提那些看起来能跑、换个文件就报错的诡异情况——合并单元格读出来是 None、Word 里的表格跨页后行数对不上、生成的文档打开提示内容有问题需要修复。这篇是 Python 系列的第一篇专门聊创建和解析 Office 文档这件事。所谓创建就是让程序从零生成一份 Word、Excel 或 PowerPoint所谓解析就是把已有的文档拆开把里面的文字、表格、样式、公式读出来变成程序能处理的数据。这两件事合起来基本覆盖了日常办公自动化的八成场景批量生成合同、自动填报表、从报告里提取关键指标、把数据表转成图文并茂的汇报材料。适合谁看如果你已经会写基本的 Python 循环和函数但一碰到.docx、.xlsx就不知道从哪下手这篇就是给你准备的。我会把选型逻辑、核心 API 的用法、以及那些文档里不会写的踩坑经验都摊开讲。全程用从业者之间交流的口吻不绕弯子能直接抄的代码我都给出来。先说一个反直觉的结论处理 Office 文档最难的从来不是写代码而是理解文档本身的格式规范。.docx和.xlsx本质上都是 ZIP 压缩包里面装着一堆 XML。你用的库只是帮你把这层 XML 包装成了 Python 对象。理解这一点后面遇到各种莫名其妙的问题时你就能顺着 XML 结构去排查而不是对着报错干瞪眼。2. 选型之前先搞清楚你到底在跟什么格式打交道2.1 老格式和新格式是两套完全不同的东西很多人栽的第一个跟头就是没分清.doc和.docx、.xls和.xlsx。这两组看起来只差一个字母底层却是天壤之别。.doc、.xls、.ppt是微软早期的二进制格式文件内部是一段紧凑的二进制流没有公开的、友好的解析规范。Python 想读它们基本只能靠xlrd仅限 xls、pywin32调用本机 Office 组件这类方式跨平台性差还经常因为环境没装 Office 而失败。.docx、.xlsx、.pptx是 2007 年之后基于 Office Open XML 规范的格式本质是 ZIP 包加 XML。你可以直接把一个.docx的后缀改成.zip解压后能看到word/document.xml、word/styles.xml这些文件。这种开放性让第三方库可以纯 Python 解析不依赖 Office 软件本身。所以选型的第一条铁律新项目一律只支持新格式。如果业务方丢给你一堆.doc正确做法是先批量转成.docx再处理而不是硬着头皮去啃二进制。转换可以用 LibreOffice 的命令行模式批量做这个后面会讲。2.2 三大件对应的主力库文档类型创建解析说明Word (.docx)python-docxpython-docx读写一体API 直观Excel (.xlsx)openpyxlopenpyxl读写一体支持公式和样式Excel 数据分析pandaspandas适合纯数据场景不碰样式PowerPoint (.pptx)python-pptxpython-pptx读写一体老格式 (.doc/.xls)不推荐xlrd(仅xls)建议先转换这里有个常见的误区很多人一上来就用 pandas 读 Excel觉得一行pd.read_excel()就搞定何必学 openpyxl。但 pandas 的定位是数据分析它读 Excel 时会把所有内容当成数据表样式、合并单元格、公式、批注这些信息全部丢掉。如果你只是想把表格数据拿来做统计pandas 确实快但如果你要保留格式、要写回带样式的报表、要处理合并单元格就必须用 openpyxl。我的经验是数据进 pandas格式进 openpyxl。两者可以配合用 openpyxl 读带格式的原始文件把纯数据部分转成 DataFrame 做计算算完再用 openpyxl 写回带样式的模板。2.3 安装与环境准备pip install python-docx openpyxl python-pptx pandas装完之后建议先跑一个最小验证确认库能正常导入import docx import openpyxl import pptx print(docx.__version__ if hasattr(docx, __version__) else docx ok) print(openpyxl.__version__) print(pptx.__version__)注意python-docx的包名是python-docx但导入时写import docxpython-pptx导入时写import pptx。这个命名不一致坑过不少人装的时候别装成docx那个同名的老包那个是另一个项目。3. Word 文档从生成一份合同到拆解一份报告3.1 用 python-docx 从零生成文档先看创建。假设你要批量生成一批通知书每份的姓名、日期、金额不同但格式完全一样。最朴素的做法是准备一个模板然后替换占位符。但 python-docx 本身没有查找替换这种高级功能你得自己遍历段落和表格里的 run。先理解 python-docx 的对象模型一个 Document 包含若干 Paragraph段落每个 Paragraph 包含若干 Run文本片段。Run 是样式的最小单位同一段里不同字体、不同加粗的文本会被拆成多个 Run。这个模型很关键因为替换文字时如果直接改 Paragraph.text会把整段的样式全冲掉。from docx import Document from docx.shared import Pt, RGBColor from docx.enum.text import WD_ALIGN_PARAGRAPH doc Document() # 添加标题 title doc.add_heading(项目结项通知书, level1) title.alignment WD_ALIGN_PARAGRAPH.CENTER # 添加正文段落 p doc.add_paragraph(兹有) run p.add_run(张三) run.bold True run.font.color.rgb RGBColor(0xC0, 0x00, 0x00) p.add_run(同志您参与的项目已通过验收。) # 添加表格 table doc.add_table(rows3, cols2) table.style Table Grid table.cell(0, 0).text 项目名称 table.cell(0, 1).text 某跨平台系统 table.cell(1, 0).text 结项日期 table.cell(1, 1).text 2024-06-01 table.cell(2, 0).text 负责人 table.cell(2, 1).text 张三 doc.save(notice.docx)这段代码里几个点值得展开。add_heading用的是内置样式level1 对应标题 1。如果你想要自定义字体得去改样式对象而不是直接设 run 的字体——因为标题样式会覆盖 run 级别的设置。table.style Table Grid是给表格加边框不加的话默认是无框线打印出来一片空白。3.2 模板替换为什么直接改 text 会翻车批量生成场景下更实用的做法是准备一个.docx模板里面写好{{name}}、{{date}}这样的占位符然后程序读模板、替换、另存。但前面说了python-docx 没有内置替换。网上流传的写法是遍历doc.paragraphs对每个paragraph.text做replace然后重新赋值。这个写法有个致命问题它会把段落里所有 Run 的样式合并成一个。正确的做法是遍历 Run在 Run 级别替换def replace_in_paragraph(paragraph, mapping): for run in paragraph.runs: for key, value in mapping.items(): if key in run.text: run.text run.text.replace(key, value)但这里还有个坑占位符可能被拆到多个 Run 里。比如{{name}}在 Word 里可能因为编辑历史被拆成{{、name、}}三个 Run。这时候单个 Run 里根本找不到完整的占位符。解决办法有两种一是替换前先把段落里所有 Run 的文本合并判断如果占位符跨 Run就重建整个段落二是用更专业的库如docxtpl它基于 jinja2 模板引擎专门解决这个问题。我的建议是简单场景用 python-docx 手动替换复杂模板直接上 docxtpl。docxtpl 的用法是doc.render(context)context 是个字典模板里写{{ name }}还支持循环和条件判断做批量合同、证书这类场景非常省事。3.3 解析 Word表格和段落要分开处理解析比创建更容易踩坑。一个 Word 文档里文字可能出现在三个地方普通段落、表格单元格、页眉页脚。很多人只遍历doc.paragraphs结果发现表格里的内容全丢了。def extract_all_text(doc): texts [] # 普通段落 for p in doc.paragraphs: if p.text.strip(): texts.append(p.text) # 表格 for table in doc.tables: for row in table.rows: cells [cell.text.strip() for cell in row.cells] texts.append( | .join(cells)) return texts这里有个隐蔽的坑合并单元格会导致同一段文字被重复读取。比如一个横向合并的单元格row.cells会返回多个指向同一个底层单元格的对象你读到的文字就重复了。判断方法是比较 cell 的_tc属性底层 XML 元素是否相同seen set() for cell in row.cells: if id(cell._tc) not in seen: seen.add(id(cell._tc)) # 处理这个 cell另一个坑是跨页表格的行数。Word 里一个表格如果跨页python-docx 读出来仍然是一个 table 对象行数是完整的这点不用担心。但如果文档里有两个独立的表格被排版成看起来连在一起那就是两个 table需要分别处理。3.4 页眉页脚和文本框容易被忽略的角落页眉页脚的内容不在doc.paragraphs里要单独访问for section in doc.sections: header section.header for p in header.paragraphs: print(p.text) footer section.footer for p in footer.paragraphs: print(p.text)文本框Text Box更麻烦python-docx 没有直接 API得深入到 XML 层面去遍历w:txbxContent节点。如果业务文档里大量用文本框排版解析起来会非常痛苦。我的经验是如果解析需求涉及文本框先评估能不能让业务方改用普通段落实在不行再上 XML 解析。4. Excel 文档数据、公式、样式三条线要分开走4.1 openpyxl 的读写基本盘Excel 是办公自动化里出现频率最高的。openpyxl 的核心对象是 Workbook、Worksheet、Cell。读一个文件import openpyxl wb openpyxl.load_workbook(data.xlsx, data_onlyTrue) ws wb[Sheet1] for row in ws.iter_rows(min_row2, values_onlyTrue): name, age, score row print(name, age, score)这里data_onlyTrue是个关键参数。Excel 单元格里存的可能是公式比如A1B1。默认情况下 openpyxl 读出来的是公式字符串本身设了data_onlyTrue它读的是公式上一次被 Excel 计算后缓存的结果。注意这个缓存值只有在文件被 Excel 打开并保存过之后才存在。如果文件是程序生成的、从没被 Excel 打开过data_onlyTrue读出来会是 None。这个坑非常隐蔽很多人卡在这里半天找不到原因。写文件wb openpyxl.Workbook() ws wb.active ws.title 汇总 ws.append([姓名, 部门, 金额]) ws.append([张三, 研发, 12000]) ws[D1] SUM(C2:C2) wb.save(output.xlsx)ws.append()按行追加适合从列表批量写入。写公式直接写字符串但注意公式里的函数名和参数分隔符要符合 Excel 规范中文版 Excel 用逗号分隔参数这个和英文版一致不用担心。4.2 样式、合并单元格与列宽生成报表时样式很重要。openpyxl 的样式通过Font、PatternFill、Border、Alignment这些对象组合from openpyxl.styles import Font, PatternFill, Alignment, Border, Side header_font Font(name微软雅黑, size11, boldTrue, colorFFFFFF) header_fill PatternFill(solid, fgColor4472C4) center Alignment(horizontalcenter, verticalcenter) for cell in ws[1]: cell.font header_font cell.fill header_fill cell.alignment center ws.merge_cells(A1:C1) ws.column_dimensions[A].width 15合并单元格要注意合并后只有左上角那个单元格能写值其他单元格的值会被清空。读取时合并区域的非左上角单元格返回 None。如果你要遍历读取得先判断单元格是否在合并区域内或者用ws.merged_cells.ranges拿到所有合并区域自己映射回左上角。4.3 大文件处理为什么你的脚本越跑越慢openpyxl 有个性能问题它默认把整个工作簿加载到内存几万行的表还能扛几十万行就会吃光内存。这时候有两个选择。一是用read_onlyTrue模式它用流式读取内存占用小但只能顺序读不能随机访问单元格也不能修改wb openpyxl.load_workbook(big.xlsx, read_onlyTrue) ws wb.active for row in ws.iter_rows(values_onlyTrue): process(row) wb.close()二是写大文件时用write_onlyTrue配合ws.append()逐行写避免在内存里维护完整的工作表对象wb openpyxl.Workbook(write_onlyTrue) ws wb.create_sheet() for record in data_stream: ws.append(record) wb.save(big_output.xlsx)实测下来写 50 万行数据普通模式内存能飙到 2GB 以上write_only 模式稳定在几百 MB。这个差距在处理日志导出、数据备份这类场景里是决定性的。4.4 pandas 和 openpyxl 怎么配合前面说过纯数据分析用 pandas 更顺手。典型流程是用 openpyxl 读带格式的原始表把数据区转成 DataFrame 做清洗和计算再用 openpyxl 把结果写回带样式的模板。import pandas as pd import openpyxl # 读数据 df pd.read_excel(raw.xlsx, sheet_name明细, skiprows2) df[金额] df[数量] * df[单价] summary df.groupby(部门)[金额].sum().reset_index() # 写回带样式的模板 wb openpyxl.load_workbook(template.xlsx) ws wb[汇总] for i, row in summary.iterrows(): ws.cell(rowi2, column1, valuerow[部门]) ws.cell(rowi2, column2, valuerow[金额]) wb.save(report.xlsx)skiprows2是因为原始表前两行是标题和说明不是数据。这种参数要根据实际文件调整没有通用值。pandas 读 Excel 时如果表头不在第一行一定要用header和skiprows配合否则列名会错位。5. 那些文档里不会写的踩坑实录5.1 文件被占用导致保存失败最常见的报错之一PermissionError: [Errno 13] Permission denied。原因几乎都是目标文件正在被 Excel 或 Word 打开。Windows 下 Office 会锁定文件程序写不进去。解决办法不是加 try-except 硬扛而是从流程上避免生成的文件名带时间戳或者先写到临时文件再移动。import os import tempfile import shutil tmp tempfile.NamedTemporaryFile(suffix.xlsx, deleteFalse) wb.save(tmp.name) tmp.close() shutil.move(tmp.name, output.xlsx)这样即使 output.xlsx 被占用也只是最后一步 move 失败不会丢数据。5.2 中文乱码与字体问题生成的文档里中文显示成方框通常是字体没设对。python-docx 默认用 Calibri这个字体不含中文字形。解决办法是显式设置中文字体from docx.oxml.ns import qn run p.add_run(中文内容) run.font.name 微软雅黑 run._element.rPr.rFonts.set(qn(w:eastAsia), 微软雅黑)注意那个w:eastAsia的设置只设font.name对中文不生效必须同时设 eastAsia 属性。这是 python-docx 的一个历史遗留问题官方文档里提得很少但实际项目里几乎必踩。5.3 日期格式的坑Excel 里的日期本质是个浮点数整数部分是天数小数部分是时间。openpyxl 读出来可能是 datetime 对象也可能是数字取决于单元格格式。如果读出来是数字用openpyxl.utils.datetime.from_excel()转换。写日期时直接写 datetime 对象openpyxl 会自动处理格式如果写字符串Excel 会当成文本后续没法做日期计算。5.4 批量转换老格式前面提到.doc转.docx用 LibreOffice 命令行最省事soffice --headless --convert-to docx --outdir ./converted ./old_files/*.doc这个命令在 Linux 和 Windows 都能用Windows 下是soffice.exe。转换是批量的但要注意 LibreOffice 的排版引擎和微软 Office 有细微差异复杂排版的文档转换后可能错位。所以转换后最好抽样检查几份。6. 把创建和解析串成一条流水线单点操作会了之后真正的价值在于把创建和解析串起来形成自动化流水线。举个典型场景每月从多个部门收集 Excel 报表汇总后生成一份 Word 分析报告。流程拆解先用 openpyxl 遍历各部门的 Excel读取数据并校验比如检查必填列是否为空、数值是否在合理范围把校验通过的数据汇总到一个 DataFrame做统计计算然后用 python-docx 打开报告模板把统计结果填入对应的占位符和表格最后保存并归档。这个流水线里校验环节最容易被忽略但最重要。我见过太多脚本因为某个部门的表多了一行空行、或者列顺序变了就直接崩溃。健壮的做法是读取时用列名定位而不是列号遇到缺失列记录警告并跳过该文件而不是让整个流程挂掉。required_cols [部门, 项目, 金额] for file in files: try: df pd.read_excel(file) missing [c for c in required_cols if c not in df.columns] if missing: log.warning(f{file} 缺少列: {missing}跳过) continue # 继续处理 except Exception as e: log.error(f{file} 读取失败: {e}) continue这种跳过坏数据、记录日志、继续处理的模式在生产环境里比一遇错就抛异常实用得多。因为批量任务里个别文件有问题不应该影响整体。再补一个经验生成文档时保留中间产物。比如汇总的 DataFrame 存一份 CSV填充后的 Word 存一份草稿这样出问题时能快速定位是哪一步错了而不是从头重跑。这个习惯在调试阶段能省大量时间。7. 几个提升效率的实用技巧第一个技巧是关于路径处理的。Windows 下路径用反斜杠Linux 用正斜杠写死任何一种都会在另一个平台翻车。统一用pathlibfrom pathlib import Path base Path(data) for f in base.glob(*.xlsx): print(f.name, f.stem, f.suffix)glob支持通配符stem是不带后缀的文件名这些比字符串拼接靠谱得多。第二个技巧是给文档操作加日志。批量处理几十上百个文件时出问题在所难免有日志才能快速定位。用标准库的 logging配置成同时输出到控制台和文件import logging logging.basicConfig( levellogging.INFO, format%(asctime)s %(levelname)s %(message)s, handlers[logging.FileHandler(process.log), logging.StreamHandler()] )第三个技巧是处理超大批量时的进度反馈。用tqdm包一层循环能直观看到进度和预估剩余时间from tqdm import tqdm for f in tqdm(files, desc处理中): process(f)第四个技巧也是我个人踩坑最多的一条永远不要相信输入文件的格式是规范的。业务方给你的 Excel可能有隐藏行、有筛选状态、有冻结窗格、有数据验证、有批注这些在 openpyxl 里读出来都是额外的属性。如果你的脚本只关心数据读的时候用values_onlyTrue忽略格式如果关心格式就要做好遇到各种意外属性的准备。最稳妥的做法是先用一个小脚本把文件的结构打印出来看看再写正式处理逻辑。wb openpyxl.load_workbook(unknown.xlsx) for ws in wb.worksheets: print(fSheet: {ws.title}, 维度: {ws.dimensions}, 最大行: {ws.max_row}, 最大列: {ws.max_column}) print(f合并区域: {list(ws.merged_cells.ranges)}) print(f冻结窗格: {ws.freeze_panes})这几行打印出来的信息能帮你快速判断这个文件干净不干净值不值得直接上自动化还是需要先做一轮清洗。Office 文档自动化这件事库的 API 只是表层真正决定成败的是你对文档格式的理解和对异常情况的预判。把上面这些坑都趟过一遍之后你会发现大部分问题都有规律可循无非是格式差异、样式覆盖、文件占用这几类。下一篇我会聊 PDF 和图片的处理那又是另一套完全不同的逻辑了。
