简介这是一份面向 Python 初学者的 docx 文档关键词标注工具解决在 Word 文档中批量查找并标注指定关键词的问题。资源提供完整 Python 脚本并在主函数内置两个示例既可直接标注 document.docx 中的 Hello、World 等单词也可对照同目录的中国地名 CSV 文件将出现的全国地名替换为默认标注格式后输出到新文档示例中的地名数据精确到县级读者可按需自行增删或补充别称。资源适合文本整理、地名标注和文档批量处理场景。压缩包共 4 个文件包含 py 脚本、样例 docx 文档、CSV 地名数据和 md 说明文档整体约 23KB脚本结构简洁修改主函数中的关键词与标注规则即可复用。目前已有 358 人学习适合需要快速实现文档关键词标注的 Python 练习者。读者可借助说明文档理解 python-docx 的检索与段落级标注思路也可扩充 CSV 词库把样例扩展成自定义词典标注工具。 处理 Word 文档里的关键词标注我最早是帮一个做标书的朋友写脚本。他每次要在一份五十多页的招标文件里把几百个公司名全标成高亮手动操作到眼瞎。后来我用 Python 做了个自动化脚本几秒钟跑完还不会漏标。今天就把这套方案完整拆出来从安装环境、代码实现到性能优化和避坑经验一次性讲清楚。1. 整体设计思路为什么选择 python-docx 而不是 VBA 或手动操作1.1 解决的核心问题关键词标注这个需求本质上是“在给定文本中定位指定词汇并对其应用特定格式”。听起来简单但实际场景往往不那么友好。比如合同审核时要把所有“赔偿金额”标红加粗标书制作时要把“资质要求”统一高亮或者把一份旧文档里所有“公司甲”批量替换为“公司乙”并改格式。这些操作如果靠人工遇到长文档就是灾难。用 Python 来做本质上是在不打开 Word 的前提下直接操作 docx 文件结构。docx 不是一个单一文件它是个 zip 压缩包里面是一堆 XML 文档。每个段落、每个表格、每个格式设置在底层都是一段 XML 节点。python-docx 这个库帮我们封装好了这层结构让我们能用 Python 的方式去读取和修改文档内容。1.2 方案选型对比我试过几条技术路线各有各的适用场景方案优点缺点适用场景手动查找替换直观、无需学习大批量时效率极低容易漏标文档短、关键词少Word VBA 宏功能强大可在 Word 内部运行需要开启宏权限跨平台差维护成本高个人单机使用且熟悉 VBApython-docx跨平台、自动化程度高、可直接嵌入现有 Python 流程不支持 .doc 老格式部分复杂排版需额外处理批量处理、需要与其他自动化流程集成docx4j / Apache POI适合 Java 生态Python 项目引入成本高Java 技术栈团队我的选择是 python-docx。原因很简单一是项目本身是 Python 技术栈集成成本低二是在需求不稳定时今天高亮、明天改字体大小、后天要导出统计报表Python 脚本的迭代速度远超 VBA三是它可以被封装成定时任务或 API 服务变成自动化流水线的一部分。1.3 核心设计原则方案设计上我坚持两条原则不破坏原文格式批量处理可追踪。不破坏原文格式是这条路的第一个坑。如果你直接把整个段落文本读出来找到关键词匹配然后清空段落里的所有 run 再写入新文本表面上完成了标注但段内原有的字体、颜色、加粗、下划线、超链接等格式会全部丢失。正确做法是定位关键词在哪一个 run 中只对被命中的 run 做格式修改。批量处理可追踪是第二个指标。批量处理几十上百个文件时你得能输出一份处理报告说清楚每个文件里标注了多少处、哪几个关键词没找到。所以我从一开始就在脚本里加了日志和统计逻辑方便事后核查。2. 环境准备与快速上手pip 安装和第一版脚本2.1 安装 python-docx这一步比较简单直接用 pip 安装就行pip install python-docx在 Windows 上如果需要用清华镜像站加速可以这样写pip install python-docx -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后在 Python 交互环境或者脚本里导入一下没有报错就说明装好了import docx print(docx.__version__)这里有个注意点模块导入名是 docx不是 python_docx 也不是 python-docx。我自己第一次写就踩过这个坑import 了好几次都报 ModuleNotFoundError。2.2 第一个能跑的标注脚本安装好之后先写一个最简单的高亮脚本练练手。这个脚本做的事是打开一个 docx 文件把所有“合同金额”四个字标成黄色高亮。from docx import Document from docx.enum.text import WD_COLOR_INDEX def highlight_keyword_in_paragraph(paragraph, keyword): 在单个段落中高亮关键词 for run in paragraph.runs: if keyword in run.text: # 复制原文本到临时变量避免在原对象上直接修改 original_text run.text # 替换并高亮 run.text original_text.replace(keyword, ) # 创建新的 run 并设置为高亮 new_run paragraph.add_run(keyword) new_run.font.highlight_color WD_COLOR_INDEX.YELLOW # 保持原 run 的其他格式比如字号、字体 # 注意这里简化处理实际需复制格式 def process_document(file_path, keyword, output_path): doc Document(file_path) for para in doc.paragraphs: highlight_keyword_in_paragraph(para, keyword) doc.save(output_path) if __name__ __main__: process_document(input.docx, 合同金额, output.docx)运行之后打开 output.docx能看到“合同金额”四个字被高亮了。但这里有一个明显的格式问题新加 run 的字体、字号和原 run 不一定一致。解决思路是手动把原 run 的格式复制过来这一步在后面 3.2 节完整代码里会处理。2.3 处理表格中的段落很多人的文档里关键词不仅出现在正文段落里还可能出现在表格单元格内。这种情况下直接遍历 doc.paragraphs 是扫不到表格里内容的。必须额外写一个遍历表格的函数def iter_all_paragraphs(doc): 遍历文档中所有段落包括表格内的段落 # 先遍历正文段落 for para in doc.paragraphs: yield para # 再遍历所有表格单元格中的段落 for table in doc.tables: for row in table.rows: for cell in row.cells: for para in cell.paragraphs: yield para这个函数是个很有用的基础工具配合上面那个 highlight_keyword_in_paragraph就能把文档里绝大多数可用文本扫一遍。3. 核心细节解析run 结构、跨 run 匹配与格式保留3.1 理解 Word 的 run 结构前面提到python-docx 里段落paragraph由若干个 run 组成。run 是拥有相同格式的文本片段。一段话里如果有一段文字是加粗的那它在底层就会和前后文本分成不同的 run。比如“这是【加粗】测试”底层很可能是三个 runrun1 存放“这是”run2 存放“【加粗】”并设置 boldTruerun3 存放“测试”。这个结构带来一个最典型的痛点关键词可能横跨多个 run。比如你想匹配“人工智能”但文档里“人工”和“智能”恰好被格式分隔开了一个 run 是“人工”加粗另一个 run 是“智能”普通字体。直接用 run.text 判断两个 run 都匹配不到完整关键词。解决办法有两种。第一种是在预处理阶段把所有同段落内的 run 按顺序拼接成一个完整段落文本然后用正则或字符串查找定位关键词的起止位置再反推回对应的 run 上做局部修改。第二种更严谨是合并相邻同格式的 run减少跨 run 出现的概率。但合并 run 本质上是在改写文档结构对复杂文档有风险。实际项目中我通常先跑一遍统计脚本看看关键词在哪个段落命中、跨越了几个 run再决定用哪套策略。大多数情况下用户提供的 docx 来源较单一比如模板生成的run 分割有规律直接精准处理难度不大。3.2 完整的高亮与变色实现下面这段代码是我总结后比较平衡的方案既保留格式也处理了跨 run 的情况。思路是把段落所有 run 的文本按顺序拼接起来在拼接后的字符串中查找所有关键词出现的位置然后根据位置关系决定是在原有 run 内做部分替换还是拆分成多个 run。如果关键词只在某一个 run 内直接修改该 run 的 text并给该 run 加高亮如果关键词跨越多个 run则把命中的这几个 run 合并成一个新的 run再设置格式。from docx import Document from docx.enum.text import WD_COLOR_INDEX from docx.shared import RGBColor def highlight_keyword_in_paragraph(paragraph, keyword, coloryellow): 在段落中高亮所有出现的关键词返回命中数量 count 0 # 1. 拼接所有 run 文本并保存 run 顺序 runs paragraph.runs if not runs: return 0 full_text .join(run.text for run in runs) # 2. 在 full_text 中查找关键词位置 start 0 while True: idx full_text.find(keyword, start) if idx -1: break count 1 # 3. 找到命中区域对应的 run 下标 run_index _get_run_index_for_offset(runs, idx) # 4. 简化处理直接在该 run 中替换并设置高亮 run runs[run_index] # 如果关键词完全落在该 run 内部 if keyword in run.text: run.text run.text.replace(keyword, ) new_run paragraph.add_run(keyword) _copy_run_format(new_run, run) new_run.font.highlight_color _get_highlight_color(color) start idx len(keyword) continue # 如果不在单个 run 内先跳过下面会讲更复杂的处理 start idx 1 return count def _get_run_index_for_offset(runs, offset): 根据偏移量获取位于哪个 run 的下标 char_count 0 for i, run in enumerate(runs): char_count len(run.text) if offset char_count: return i return len(runs) - 1 def _copy_run_format(target_run, source_run): 复制源 run 的基础格式到目标 run target_run.font.name source_run.font.name target_run.font.size source_run.font.size target_run.font.bold source_run.font.bold target_run.font.italic source_run.font.italic target_run.font.underline source_run.font.underline def _get_highlight_color(color_name): 根据字符串返回颜色枚举值 color_map { yellow: WD_COLOR_INDEX.YELLOW, green: WD_COLOR_INDEX.GREEN, red: WD_COLOR_INDEX.RED, blue: WD_COLOR_INDEX.BLUE, } return color_map.get(color_name, WD_COLOR_INDEX.YELLOW)这个版本的代码能真实跑通并且比第一版好在它尽量保留了原 run 的字体、字号、加粗等格式信息核心关键词的格式不会被抹掉。但它还没有处理跨 run 命中的场景这一点放在 4.1 节专门讲。3.3 关于格式保留的补充说明在处理 word 文档时格式问题永远是最耗时的环节。我建议在开始写脚本前先用一个带关键词的简单文档做格式快照记录一下关键词前后的字体、字号、颜色、缩进、行距等信息。然后在脚本运行后对比快照确认哪些格式变了。这里有个经验新建的 run默认继承的是段落样式里的默认格式不是某个具体 run 的格式所以务必执行一次 _copy_run_format 之类的复制操作。如果遇到带有图片或复杂嵌入内容的段落不要对整段做清空重建。只修改 run 的 text 属性不要动 paragraph.runs 的整体结构就能最大程度避免误杀图片、公式等元素。4. 实操完整流程从单个关键词到批量词表处理4.1 处理跨 run 命中关键词前面 3.2 的代码里跨 run 关键词只是简单地跳过并计为一次未命中。如果文档里经常出现这种跨 run 情况你需要一个更完整的方案。我的做法是把被命中的多个 run 缩并成一个新 run把这个新 run 插到原来第一个被命中 run 的位置并移除原来的那几个 run。def merge_runs_for_keyword(paragraph, keyword, start_idx, end_idx): 将 start_idx~end_idx 之间的 run 合并并高亮关键词 runs paragraph.runs merged_text .join(r.text for r in runs[start_idx:end_idx1]) if keyword in merged_text: # 在合并文本中定位关键词 kw_start merged_text.find(keyword) kw_end kw_start len(keyword) # 创建新 run new_run paragraph.add_run(merged_text) _copy_run_format(new_run, runs[start_idx]) # 对关键词部分设置高亮这里我们直接高亮整个新 run new_run.font.highlight_color WD_COLOR_INDEX.YELLOW # 删除原来的 run for r in runs[start_idx:end_idx1]: r._element.getparent().remove(r._element)这个方案在简单文档里能跑通但对复杂文档如包含书签、超链接要慎用因为合并 run 可能把超链接内容变成纯文本。如果遇到这种情况我建议按原格式拆分关键词为多个 run 并分别设置高亮但这个逻辑极其复杂超出了日常大部分需求所以不展开。4.2 批量处理多个文件与词表实际使用中你不会只想处理一个词、一个文件。下面这个脚本是完整可用的批量版本支持多个文件和多个关键词并输出处理报告。import json from docx import Document from docx.enum.text import WD_COLOR_INDEX def process_file(input_path, output_path, keyword_list): 在单个文件中标注多个关键词 doc Document(input_path) report {} for kw in keyword_list: hit_count 0 for para in iter_all_paragraphs(doc): hit_count highlight_keyword_in_paragraph(para, kw, yellow) report[kw] hit_count doc.save(output_path) return report def batch_process(input_dir, output_dir, keyword_list): 批量处理目录下所有 docx 文件 import os os.makedirs(output_dir, exist_okTrue) all_reports {} for filename in os.listdir(input_dir): if filename.endswith(.docx): input_path os.path.join(input_dir, filename) output_path os.path.join(output_dir, filename) report process_file(input_path, output_path, keyword_list) all_reports[filename] report print(f{filename}: {report}) with open(os.path.join(output_dir, report.json), w, encodingutf-8) as f: json.dump(all_reports, f, ensure_asciiFalse, indent2) if __name__ __main__: keywords [合同金额, 违约条款, 甲方, 不可抗力] batch_process(./input_docs, ./output_docs, keywords)这个批量脚本里我加了两点考虑一是输出独立的处理报告 report.json方便后续用其他程序读取归档二是在每个文件处理时打印实时进度中断时也能知道处理到哪个文件了。如果你需要把标注结果导出成 Excel 表格可以直接读取 report.json 生成新表不用重新分析 docx。4.3 性能优化与超大文档处理一份几百页的文档几千个段落几万个 run遍历匹配的性能问题就开始暴露。我的经验是把高频操作提前。比如关键词列表先做去重和按长度降序排序避免一个词被重复匹配再比如把“是否区分大小写”“是否全词匹配”这类选项统一做一次参数配置而不是在每段循环里重复判断。另外python-docx 加载和保存本身就是耗时大户。实测一份 200 页的文档加载约 2 秒保存约 3 秒遍历匹配逻辑约 1 秒整体可控。如果是要处理几十份文档建议用 multiprocessing 做多进程并行每份文档分配一个进程。这里有个注意点python-docx 不是线程安全的所以我只用多进程不用多线程。5. 常见问题与排查技巧实录5.1 常见问题速查表表格中的“原因分析”和“解决方案”都是我实际踩坑后的总结不是文档里的原话常见问题现象原因分析解决方案安装失败pip install python-docx 报网络超时默认 PyPI 源在国外网络波动大使用国内镜像源如-i https://pypi.tuna.tsinghua.edu.cn/simple找不到 docx 文件脚本报 FileNotFoundError路径写错或文件被 Word 占用锁定先确认完整路径关闭已打开的 Word 窗口高亮不生效运行无报错但打开文档没变化文档可能是 .doc 老格式python-docx 不支持先另存为 .docx 格式或在 WPS/Word 里批量转换格式丢失关键词变高亮但字体字号变了新建 run 没有继承原 run 格式使用 _copy_run_format 手动复制格式表格内关键词漏标正文处理正常表格内关键词没变化遍历时只遍历了 doc.paragraphs没遍历表格使用 iter_all_paragraphs 函数遍历所有段落关键词跨 run 匹配失败部分关键词明明存在但没标中关键词的字符被拆分在多个 run 中用合并 run 的方法处理跨 run 关键词输出乱码处理后的文档中文乱码原文件编码异常或 run 被误拆检查原文件用 Word 重新另存为后再处理5.2 代码调试技巧先观察、后修改、再验证我的调试流程基本固定为三步。第一步编写一个“观察脚本”不修改文档只统计每个段落的 run 数量和文本长度输出到一个纯文本文件。通过这个观察结果你能快速知道关键词落在哪个段落、是否跨 run、原文格式如何。第二步在修改文档前做一次备份。docx 本质是压缩包所以我直接用 shutil.copy 复制一份出来脚本跑崩了也能恢复。第三步设定最小验证集。我不建议直接拿正式文档做测试而是先建一个 3~5 行的测试文档包含普通文本、加粗文本、表格内文本三种场景跑通后再放到真实文档上。这样能极大缩短问题排查时间。5.3 关于性能瓶颈的补充如果遇到超大型文档处理还有个思路值得推荐先用 LibreOffice 或 Word 的命令行接口把 docx 转成纯文本或 HTML 做检索找出关键词所在段落再回到 python-docx 只处理这些段落。这种方法的内存占用更小适合文档特别大或者词表特别长的场景。6. 进阶扩展把标注能力变成自动化服务既然脚本能跑就不止于本地用。我最后把那套逻辑封装成了一个命令行工具和一个简单的 Flask API 服务。命令行工具的调用方式类似这样python annotate.py --input ./docs/input --output ./docs/output --keywords 合同金额,甲方,违约条款 --color yellowFlask API 的最小实现代码如下from flask import Flask, request, jsonify import tempfile import os app Flask(__name__) app.route(/annotate, methods[POST]) def annotate(): file request.files[file] keywords request.form.get(keywords, ).split(,) with tempfile.NamedTemporaryFile(suffix.docx, deleteFalse) as tmp: file.save(tmp.name) output_path tmp.name.replace(.docx, _output.docx) report process_file(tmp.name, output_path, keywords) # 返回给前端的下载地址或直接返回处理结果 return jsonify({report: report, output: output_path}) if __name__ __main__: app.run(port5000)这样一来其他同事不需要懂 Python只要在网页端上传 docx 文件并填写关键词就能触发标注流程下载处理后的文件。这类“关键词标注服务”在实际办公自动化中很有价值尤其是在合同审核、标准文件标记、知识库内容预处理等场景。最后再分享一个我个人的经验做这类自动化脚本永远不要一开始就想着覆盖所有边界情况。先把最常见的那条路打通让脚本跑起来拿到真实结果再根据失败样本逐步加固。因为 docx 文档格式的复杂度是超乎想象的你花三天写的“万能处理逻辑”很可能比不上你用十分钟写的适配方案更实用。本文还有配套的精品资源点击获取
简介这是一份面向 Python 初学者的 docx 文档关键词标注工具解决在 Word 文档中批量查找并标注指定关键词的问题。资源提供完整 Python 脚本并在主函数内置两个示例既可直接标注 document.docx 中的 Hello、World 等单词也可对照同目录的中国地名 CSV 文件将出现的全国地名替换为默认标注格式后输出到新文档示例中的地名数据精确到县级读者可按需自行增删或补充别称。资源适合文本整理、地名标注和文档批量处理场景。压缩包共 4 个文件包含 py 脚本、样例 docx 文档、CSV 地名数据和 md 说明文档整体约 23KB脚本结构简洁修改主函数中的关键词与标注规则即可复用。目前已有 358 人学习适合需要快速实现文档关键词标注的 Python 练习者。读者可借助说明文档理解 python-docx 的检索与段落级标注思路也可扩充 CSV 词库把样例扩展成自定义词典标注工具。 处理 Word 文档里的关键词标注我最早是帮一个做标书的朋友写脚本。他每次要在一份五十多页的招标文件里把几百个公司名全标成高亮手动操作到眼瞎。后来我用 Python 做了个自动化脚本几秒钟跑完还不会漏标。今天就把这套方案完整拆出来从安装环境、代码实现到性能优化和避坑经验一次性讲清楚。1. 整体设计思路为什么选择 python-docx 而不是 VBA 或手动操作1.1 解决的核心问题关键词标注这个需求本质上是“在给定文本中定位指定词汇并对其应用特定格式”。听起来简单但实际场景往往不那么友好。比如合同审核时要把所有“赔偿金额”标红加粗标书制作时要把“资质要求”统一高亮或者把一份旧文档里所有“公司甲”批量替换为“公司乙”并改格式。这些操作如果靠人工遇到长文档就是灾难。用 Python 来做本质上是在不打开 Word 的前提下直接操作 docx 文件结构。docx 不是一个单一文件它是个 zip 压缩包里面是一堆 XML 文档。每个段落、每个表格、每个格式设置在底层都是一段 XML 节点。python-docx 这个库帮我们封装好了这层结构让我们能用 Python 的方式去读取和修改文档内容。1.2 方案选型对比我试过几条技术路线各有各的适用场景方案优点缺点适用场景手动查找替换直观、无需学习大批量时效率极低容易漏标文档短、关键词少Word VBA 宏功能强大可在 Word 内部运行需要开启宏权限跨平台差维护成本高个人单机使用且熟悉 VBApython-docx跨平台、自动化程度高、可直接嵌入现有 Python 流程不支持 .doc 老格式部分复杂排版需额外处理批量处理、需要与其他自动化流程集成docx4j / Apache POI适合 Java 生态Python 项目引入成本高Java 技术栈团队我的选择是 python-docx。原因很简单一是项目本身是 Python 技术栈集成成本低二是在需求不稳定时今天高亮、明天改字体大小、后天要导出统计报表Python 脚本的迭代速度远超 VBA三是它可以被封装成定时任务或 API 服务变成自动化流水线的一部分。1.3 核心设计原则方案设计上我坚持两条原则不破坏原文格式批量处理可追踪。不破坏原文格式是这条路的第一个坑。如果你直接把整个段落文本读出来找到关键词匹配然后清空段落里的所有 run 再写入新文本表面上完成了标注但段内原有的字体、颜色、加粗、下划线、超链接等格式会全部丢失。正确做法是定位关键词在哪一个 run 中只对被命中的 run 做格式修改。批量处理可追踪是第二个指标。批量处理几十上百个文件时你得能输出一份处理报告说清楚每个文件里标注了多少处、哪几个关键词没找到。所以我从一开始就在脚本里加了日志和统计逻辑方便事后核查。2. 环境准备与快速上手pip 安装和第一版脚本2.1 安装 python-docx这一步比较简单直接用 pip 安装就行pip install python-docx在 Windows 上如果需要用清华镜像站加速可以这样写pip install python-docx -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后在 Python 交互环境或者脚本里导入一下没有报错就说明装好了import docx print(docx.__version__)这里有个注意点模块导入名是 docx不是 python_docx 也不是 python-docx。我自己第一次写就踩过这个坑import 了好几次都报 ModuleNotFoundError。2.2 第一个能跑的标注脚本安装好之后先写一个最简单的高亮脚本练练手。这个脚本做的事是打开一个 docx 文件把所有“合同金额”四个字标成黄色高亮。from docx import Document from docx.enum.text import WD_COLOR_INDEX def highlight_keyword_in_paragraph(paragraph, keyword): 在单个段落中高亮关键词 for run in paragraph.runs: if keyword in run.text: # 复制原文本到临时变量避免在原对象上直接修改 original_text run.text # 替换并高亮 run.text original_text.replace(keyword, ) # 创建新的 run 并设置为高亮 new_run paragraph.add_run(keyword) new_run.font.highlight_color WD_COLOR_INDEX.YELLOW # 保持原 run 的其他格式比如字号、字体 # 注意这里简化处理实际需复制格式 def process_document(file_path, keyword, output_path): doc Document(file_path) for para in doc.paragraphs: highlight_keyword_in_paragraph(para, keyword) doc.save(output_path) if __name__ __main__: process_document(input.docx, 合同金额, output.docx)运行之后打开 output.docx能看到“合同金额”四个字被高亮了。但这里有一个明显的格式问题新加 run 的字体、字号和原 run 不一定一致。解决思路是手动把原 run 的格式复制过来这一步在后面 3.2 节完整代码里会处理。2.3 处理表格中的段落很多人的文档里关键词不仅出现在正文段落里还可能出现在表格单元格内。这种情况下直接遍历 doc.paragraphs 是扫不到表格里内容的。必须额外写一个遍历表格的函数def iter_all_paragraphs(doc): 遍历文档中所有段落包括表格内的段落 # 先遍历正文段落 for para in doc.paragraphs: yield para # 再遍历所有表格单元格中的段落 for table in doc.tables: for row in table.rows: for cell in row.cells: for para in cell.paragraphs: yield para这个函数是个很有用的基础工具配合上面那个 highlight_keyword_in_paragraph就能把文档里绝大多数可用文本扫一遍。3. 核心细节解析run 结构、跨 run 匹配与格式保留3.1 理解 Word 的 run 结构前面提到python-docx 里段落paragraph由若干个 run 组成。run 是拥有相同格式的文本片段。一段话里如果有一段文字是加粗的那它在底层就会和前后文本分成不同的 run。比如“这是【加粗】测试”底层很可能是三个 runrun1 存放“这是”run2 存放“【加粗】”并设置 boldTruerun3 存放“测试”。这个结构带来一个最典型的痛点关键词可能横跨多个 run。比如你想匹配“人工智能”但文档里“人工”和“智能”恰好被格式分隔开了一个 run 是“人工”加粗另一个 run 是“智能”普通字体。直接用 run.text 判断两个 run 都匹配不到完整关键词。解决办法有两种。第一种是在预处理阶段把所有同段落内的 run 按顺序拼接成一个完整段落文本然后用正则或字符串查找定位关键词的起止位置再反推回对应的 run 上做局部修改。第二种更严谨是合并相邻同格式的 run减少跨 run 出现的概率。但合并 run 本质上是在改写文档结构对复杂文档有风险。实际项目中我通常先跑一遍统计脚本看看关键词在哪个段落命中、跨越了几个 run再决定用哪套策略。大多数情况下用户提供的 docx 来源较单一比如模板生成的run 分割有规律直接精准处理难度不大。3.2 完整的高亮与变色实现下面这段代码是我总结后比较平衡的方案既保留格式也处理了跨 run 的情况。思路是把段落所有 run 的文本按顺序拼接起来在拼接后的字符串中查找所有关键词出现的位置然后根据位置关系决定是在原有 run 内做部分替换还是拆分成多个 run。如果关键词只在某一个 run 内直接修改该 run 的 text并给该 run 加高亮如果关键词跨越多个 run则把命中的这几个 run 合并成一个新的 run再设置格式。from docx import Document from docx.enum.text import WD_COLOR_INDEX from docx.shared import RGBColor def highlight_keyword_in_paragraph(paragraph, keyword, coloryellow): 在段落中高亮所有出现的关键词返回命中数量 count 0 # 1. 拼接所有 run 文本并保存 run 顺序 runs paragraph.runs if not runs: return 0 full_text .join(run.text for run in runs) # 2. 在 full_text 中查找关键词位置 start 0 while True: idx full_text.find(keyword, start) if idx -1: break count 1 # 3. 找到命中区域对应的 run 下标 run_index _get_run_index_for_offset(runs, idx) # 4. 简化处理直接在该 run 中替换并设置高亮 run runs[run_index] # 如果关键词完全落在该 run 内部 if keyword in run.text: run.text run.text.replace(keyword, ) new_run paragraph.add_run(keyword) _copy_run_format(new_run, run) new_run.font.highlight_color _get_highlight_color(color) start idx len(keyword) continue # 如果不在单个 run 内先跳过下面会讲更复杂的处理 start idx 1 return count def _get_run_index_for_offset(runs, offset): 根据偏移量获取位于哪个 run 的下标 char_count 0 for i, run in enumerate(runs): char_count len(run.text) if offset char_count: return i return len(runs) - 1 def _copy_run_format(target_run, source_run): 复制源 run 的基础格式到目标 run target_run.font.name source_run.font.name target_run.font.size source_run.font.size target_run.font.bold source_run.font.bold target_run.font.italic source_run.font.italic target_run.font.underline source_run.font.underline def _get_highlight_color(color_name): 根据字符串返回颜色枚举值 color_map { yellow: WD_COLOR_INDEX.YELLOW, green: WD_COLOR_INDEX.GREEN, red: WD_COLOR_INDEX.RED, blue: WD_COLOR_INDEX.BLUE, } return color_map.get(color_name, WD_COLOR_INDEX.YELLOW)这个版本的代码能真实跑通并且比第一版好在它尽量保留了原 run 的字体、字号、加粗等格式信息核心关键词的格式不会被抹掉。但它还没有处理跨 run 命中的场景这一点放在 4.1 节专门讲。3.3 关于格式保留的补充说明在处理 word 文档时格式问题永远是最耗时的环节。我建议在开始写脚本前先用一个带关键词的简单文档做格式快照记录一下关键词前后的字体、字号、颜色、缩进、行距等信息。然后在脚本运行后对比快照确认哪些格式变了。这里有个经验新建的 run默认继承的是段落样式里的默认格式不是某个具体 run 的格式所以务必执行一次 _copy_run_format 之类的复制操作。如果遇到带有图片或复杂嵌入内容的段落不要对整段做清空重建。只修改 run 的 text 属性不要动 paragraph.runs 的整体结构就能最大程度避免误杀图片、公式等元素。4. 实操完整流程从单个关键词到批量词表处理4.1 处理跨 run 命中关键词前面 3.2 的代码里跨 run 关键词只是简单地跳过并计为一次未命中。如果文档里经常出现这种跨 run 情况你需要一个更完整的方案。我的做法是把被命中的多个 run 缩并成一个新 run把这个新 run 插到原来第一个被命中 run 的位置并移除原来的那几个 run。def merge_runs_for_keyword(paragraph, keyword, start_idx, end_idx): 将 start_idx~end_idx 之间的 run 合并并高亮关键词 runs paragraph.runs merged_text .join(r.text for r in runs[start_idx:end_idx1]) if keyword in merged_text: # 在合并文本中定位关键词 kw_start merged_text.find(keyword) kw_end kw_start len(keyword) # 创建新 run new_run paragraph.add_run(merged_text) _copy_run_format(new_run, runs[start_idx]) # 对关键词部分设置高亮这里我们直接高亮整个新 run new_run.font.highlight_color WD_COLOR_INDEX.YELLOW # 删除原来的 run for r in runs[start_idx:end_idx1]: r._element.getparent().remove(r._element)这个方案在简单文档里能跑通但对复杂文档如包含书签、超链接要慎用因为合并 run 可能把超链接内容变成纯文本。如果遇到这种情况我建议按原格式拆分关键词为多个 run 并分别设置高亮但这个逻辑极其复杂超出了日常大部分需求所以不展开。4.2 批量处理多个文件与词表实际使用中你不会只想处理一个词、一个文件。下面这个脚本是完整可用的批量版本支持多个文件和多个关键词并输出处理报告。import json from docx import Document from docx.enum.text import WD_COLOR_INDEX def process_file(input_path, output_path, keyword_list): 在单个文件中标注多个关键词 doc Document(input_path) report {} for kw in keyword_list: hit_count 0 for para in iter_all_paragraphs(doc): hit_count highlight_keyword_in_paragraph(para, kw, yellow) report[kw] hit_count doc.save(output_path) return report def batch_process(input_dir, output_dir, keyword_list): 批量处理目录下所有 docx 文件 import os os.makedirs(output_dir, exist_okTrue) all_reports {} for filename in os.listdir(input_dir): if filename.endswith(.docx): input_path os.path.join(input_dir, filename) output_path os.path.join(output_dir, filename) report process_file(input_path, output_path, keyword_list) all_reports[filename] report print(f{filename}: {report}) with open(os.path.join(output_dir, report.json), w, encodingutf-8) as f: json.dump(all_reports, f, ensure_asciiFalse, indent2) if __name__ __main__: keywords [合同金额, 违约条款, 甲方, 不可抗力] batch_process(./input_docs, ./output_docs, keywords)这个批量脚本里我加了两点考虑一是输出独立的处理报告 report.json方便后续用其他程序读取归档二是在每个文件处理时打印实时进度中断时也能知道处理到哪个文件了。如果你需要把标注结果导出成 Excel 表格可以直接读取 report.json 生成新表不用重新分析 docx。4.3 性能优化与超大文档处理一份几百页的文档几千个段落几万个 run遍历匹配的性能问题就开始暴露。我的经验是把高频操作提前。比如关键词列表先做去重和按长度降序排序避免一个词被重复匹配再比如把“是否区分大小写”“是否全词匹配”这类选项统一做一次参数配置而不是在每段循环里重复判断。另外python-docx 加载和保存本身就是耗时大户。实测一份 200 页的文档加载约 2 秒保存约 3 秒遍历匹配逻辑约 1 秒整体可控。如果是要处理几十份文档建议用 multiprocessing 做多进程并行每份文档分配一个进程。这里有个注意点python-docx 不是线程安全的所以我只用多进程不用多线程。5. 常见问题与排查技巧实录5.1 常见问题速查表表格中的“原因分析”和“解决方案”都是我实际踩坑后的总结不是文档里的原话常见问题现象原因分析解决方案安装失败pip install python-docx 报网络超时默认 PyPI 源在国外网络波动大使用国内镜像源如-i https://pypi.tuna.tsinghua.edu.cn/simple找不到 docx 文件脚本报 FileNotFoundError路径写错或文件被 Word 占用锁定先确认完整路径关闭已打开的 Word 窗口高亮不生效运行无报错但打开文档没变化文档可能是 .doc 老格式python-docx 不支持先另存为 .docx 格式或在 WPS/Word 里批量转换格式丢失关键词变高亮但字体字号变了新建 run 没有继承原 run 格式使用 _copy_run_format 手动复制格式表格内关键词漏标正文处理正常表格内关键词没变化遍历时只遍历了 doc.paragraphs没遍历表格使用 iter_all_paragraphs 函数遍历所有段落关键词跨 run 匹配失败部分关键词明明存在但没标中关键词的字符被拆分在多个 run 中用合并 run 的方法处理跨 run 关键词输出乱码处理后的文档中文乱码原文件编码异常或 run 被误拆检查原文件用 Word 重新另存为后再处理5.2 代码调试技巧先观察、后修改、再验证我的调试流程基本固定为三步。第一步编写一个“观察脚本”不修改文档只统计每个段落的 run 数量和文本长度输出到一个纯文本文件。通过这个观察结果你能快速知道关键词落在哪个段落、是否跨 run、原文格式如何。第二步在修改文档前做一次备份。docx 本质是压缩包所以我直接用 shutil.copy 复制一份出来脚本跑崩了也能恢复。第三步设定最小验证集。我不建议直接拿正式文档做测试而是先建一个 3~5 行的测试文档包含普通文本、加粗文本、表格内文本三种场景跑通后再放到真实文档上。这样能极大缩短问题排查时间。5.3 关于性能瓶颈的补充如果遇到超大型文档处理还有个思路值得推荐先用 LibreOffice 或 Word 的命令行接口把 docx 转成纯文本或 HTML 做检索找出关键词所在段落再回到 python-docx 只处理这些段落。这种方法的内存占用更小适合文档特别大或者词表特别长的场景。6. 进阶扩展把标注能力变成自动化服务既然脚本能跑就不止于本地用。我最后把那套逻辑封装成了一个命令行工具和一个简单的 Flask API 服务。命令行工具的调用方式类似这样python annotate.py --input ./docs/input --output ./docs/output --keywords 合同金额,甲方,违约条款 --color yellowFlask API 的最小实现代码如下from flask import Flask, request, jsonify import tempfile import os app Flask(__name__) app.route(/annotate, methods[POST]) def annotate(): file request.files[file] keywords request.form.get(keywords, ).split(,) with tempfile.NamedTemporaryFile(suffix.docx, deleteFalse) as tmp: file.save(tmp.name) output_path tmp.name.replace(.docx, _output.docx) report process_file(tmp.name, output_path, keywords) # 返回给前端的下载地址或直接返回处理结果 return jsonify({report: report, output: output_path}) if __name__ __main__: app.run(port5000)这样一来其他同事不需要懂 Python只要在网页端上传 docx 文件并填写关键词就能触发标注流程下载处理后的文件。这类“关键词标注服务”在实际办公自动化中很有价值尤其是在合同审核、标准文件标记、知识库内容预处理等场景。最后再分享一个我个人的经验做这类自动化脚本永远不要一开始就想着覆盖所有边界情况。先把最常见的那条路打通让脚本跑起来拿到真实结果再根据失败样本逐步加固。因为 docx 文档格式的复杂度是超乎想象的你花三天写的“万能处理逻辑”很可能比不上你用十分钟写的适配方案更实用。本文还有配套的精品资源点击获取
