接了个内部工具需求用户要在不装Office的Windows机器上用Unity客户端打开一份Word模板把模板里的【项目名称】【客户单位】【编制人】【日期】这类占位符替换成实际内容然后另存为新文档供后续打印和归档。起初我想当然地写了个File.ReadAllText然后Replace的脚本跑完生成的docx用Word打开直接提示文件损坏这才意识到docx根本不是纯文本文件不能按txt那样直接碰。后来转用NPOI插件在保留模板字体、表格框线、页眉页脚的前提下把关键字替换这条链路彻底做通了。这篇文章就把我从选型对比、Unity环境集成、替换算法到发布踩坑的完整过程写下来。需要说明的是这里讨论的不只是Unity任何基于.NET的程序需要做Word模板占位符替换都可以照着这套思路走。适合的人群大概两类一类是在Unity客户端里做报告生成功能的开发另一类是给业务部门做批量文档处理小工具的同学。1. 为什么选NPOI四个候选方案的实测对比1.1 需求被三条硬约束卡死动手之前我先花了半天把需求约束列清楚这比直接写代码有价值得多。第一条硬约束目标机器不能预装Office。部署环境里有不少机器除了系统自带的东西外什么办公软件都没有更别提Office组件了。这一条直接宣判了调用Word COM组件方案的死刑。虽然用Word COM写字符串替换代码几天就能跑通但Office版本、激活状态、权限、进程残留、平台限制这些坑会在你交付后一个个找上门。第二条硬约束输出文档必须保留模板原有的字体、字号、加粗、居中对齐、表格框线这些视觉要素。所以把docx转成HTML再读进来改写这条路也走不通一旦经过中间格式转换表格结构和样式基本就废了还原效果没法看。第三条硬约束程序要考虑Windows、Mac、Android三个平台不能绑定某个操作系统特有的能力。这又排除了P/Invoke调用系统API的思路。三条约束列完能选的只剩直接解析并修改docx文件这个方向候选方案就是Open XML SDK、DocX、NPOI这几类开源库。1.2 候选方案对比与最终选型我实际把四个方向都试了一遍整理出来的对比结果是这样方案实现原理优点缺点Open XML SDK官方维护的强类型API直接操作docx规范功能最完整对OpenXML标准支持最透彻DLL依赖多Unity里Mono/IL2CPP切换时容易出兼容问题包体偏大DocX封装OpenXML的第三方库API风格接近C#习惯生成新文档很方便新版本已经商业化集成到Unity麻烦改旧模板的能力不如生成新文档Word COM通过Interop调用本机Office组件替换逻辑最简单Word原生功能都能调需要装Office跨平台差进程和权限问题多NPOI纯托管库解析OpenXML/OLE复合文档无Office依赖DLL数量少Unity里做Excel导入导出的社区基础成熟Word模块API没有Excel方向完善个别场景需要自己绕路最终选了NPOI。理由很实际NPOI在Unity里的使用基础非常好美术、策划、程序整理Excel配置都会用到它DLL可以直接丢进Assets/Plugins目录不用处理复杂依赖它的Word模块入口在NPOI.XWPF.UserModel命名空间很多人只知道NPOI能写Excel不知道它也能读写docx这个信息差让NPOI在Word场景里被严重低估。选型阶段我用一份带表格和页眉的真实模板分别跑了三个库的DemoNPOI和Open XML SDK都能完整保留样式但NPOI集成成本低一个量级所以它就是那个够用且最不折腾的选择。2. 集成到Unity工程DLL版本、依赖与link.xml2.1 拿到正确版本的DLL并放进PluginsNPOI的Word能力不在主命名空间很多人不知道这一步导致集成时就找错了门。我以2.5.5版本为准来讲这是目前综合兼容性最好、页眉页脚API也比较完整的一个版本。操作步骤到NuGet页面搜NPOI下载2.5.5版本的.nupkg文件。拿到文件后把后缀名改成.zip直接解压。解压后进入lib目录找到netstandard2.0或net40文件夹这两个目标框架下的DLL对Unity最友好。不要用net6.0以上版本目录里的文件Unity的编译链暂时没法很好适配那种依赖。把下面这几个文件复制到Assets/Plugins/NPOI目录NPOI.dll核心基础库NPOI.OOXML.dllOOXML格式解析NPOI.OpenXml4Net.dllOpenXML容器读写本质是处理docx的zip包层级NPOI.OpenXmlFormats.dllOpenXML结构对象模型ICSharpCode.SharpZipLib.dll压缩解压依赖NPOI的zip操作全靠它在Project Settings Player Other Settings里把Api Compatibility Level设置为.NET FrameworkUnity 2021之后有些版本显示为.NET Standard 2.1实测NPOI 2.5.x也能跑。但最稳妥的组合还是.NET Framework 4.x加Mono。一个容易踩的细节DLL放进Unity后选中它们检查Inspector里的Auto Reference是否勾选平台相关设置不要误关闭。如果这几个DLL没有正常被引用编译阶段会报一堆命名空间不存在的错排查起来非常莫名其妙。版本选择上我建议直接用2.5.x不要学网上老教程用2.3.0。NPOI的页眉页脚支持是后来才补全的早期版本里doc.Headers这种属性根本不存在你照着新代码写会直接编译失败。同时我也没建议用2.6以上版本那些版本对.NET Standard的依赖升级过Unity侧的表现需要重新验证没必要追新。2.2 API兼容级别与link.xml裁剪配置如果你只在Windows编辑器里跑不配link.xml问题不大。但只要用IL2CPP方式打包比如Android、iOS、WebGL或者Windows IL2CPP模式NPOI几乎必然在运行时报FileNotFound或TypeLoadException。原因是IL2CPP的代码裁剪会把通过反射加载的类型删掉而NPOI内部大量使用反射来加载XWPFRun、XWPFParagraph这些类型一裁就完。解决办法是在Assets/link.xml里加一段保留配置linker assembly fullnameNPOI preserveall / assembly fullnameNPOI.OOXML preserveall / assembly fullnameNPOI.OpenXml4Net preserveall / assembly fullnameNPOI.OpenXmlFormats preserveall / assembly fullnameICSharpCode.SharpZipLib preserveall / /linker配好之后一定要用IL2CPP打一个Android包在真机上跑一遍完整流程再收工。只测编辑器远远不够我见过太多项目在编辑器里一切正常、上真机就崩最后查半天全是link.xml的问题。3. 关键字替换的核心算法Run内定位与跨Run合并3.1 docx内部结构XWPFDocument、段落与Run的关系要写出稳妥的替换逻辑需要先搞清楚docx的底层组织方式。docx文件本身是个zip压缩包里面最关键的是word/document.xml正文内容全在这个XML文件里。一段文字对应一个w:p节点也就是NPOI里的XWPFParagraph段落内部一个格式连续的文本片段对应一个w:r节点也就是NPOI里的XWPFRun。Run是携带字体、字号、颜色、加粗这些格式属性的最小单元。可以这样理解Word里的Run像一串珍珠项链的珠子每颗珠子有自己的颜色和大小整段文字就是由这些珠子穿成的。正常人在Word里输入【项目名称】时视觉上它是连续一串字但在XML存储层面Word完全可能把它拆成多个Run。原因很多中途切换输入法、局部设置过颜色、顺手改过一个字的字体、从别的文档复制粘贴历史遗留的样式冲突。所以替换策略千万不能只写遍历每个Run在单个Run内部找关键字否则漏替换的概率很高。正确思路是段落级检测 → 处理Run内替换 → 处理跨Run合并。3.2 Run内替换最简单也最安全的一种先看基础实现处理单Run内完整包含关键字的情况private static bool ReplaceInSingleRun(XWPFParagraph para, Dictionarystring, string replacements) { bool changed false; foreach (XWPFRun run in para.Runs) { string text run.GetText(0); if (string.IsNullOrEmpty(text)) continue; string newText text; foreach (var kvp in replacements) { if (newText.Contains(kvp.Key)) { newText newText.Replace(kvp.Key, kvp.Value); } } if (newText ! text) { run.SetText(newText, 0); changed true; } } return changed; }这里用GetText(0)而不是直接读run.Text是有讲究的。NPOI的XWPFRun.Text在某些版本里会受文档其他位置影响GetText(0)才是拿到当前Run自身文本的稳定方式写入时用SetText(processedText, 0)也是同样道理控制更精确。这个方案的优点是格式零损失因为每个Run都保持自己的样式属性。缺点是它处理不了跨Run拆分的占位符而现实恰恰是跨Run拆分经常发生。3.3 跨Run合并处理Word自动拆分的占位符当段落文本被拆进多个Run时需要把段落级文本拼接起来在完整字符串里做替换再把结果写回。我的处理策略是先遍历段落所有Run拼接全文如果发现替换项后说明这些Run共同组成的关键字需要整体重写此时采用保留第一个Run样式、删除其余Run的简化方案。public static void ReplaceInParagraph(XWPFParagraph para, Dictionarystring, string replacements) { ListXWPFRun runs para.Runs; if (runs.Count 0) return; // 把段落所有Run文本拼成完整字符串 StringBuilder sb new StringBuilder(); foreach (XWPFRun run in runs) { sb.Append(run.GetText(0)); } string fullText sb.ToString(); string result fullText; // 按字典依次替换 foreach (var kvp in replacements) { if (result.Contains(kvp.Key)) { result result.Replace(kvp.Key, kvp.Value); } } if (result fullText) return; // 没有需要处理的替换项 // 保留第一个Run的样式其余清空 while (para.Runs.Count 1) { para.RemoveRun(para.Runs.Count - 1); } runs[0].SetText(result, 0); }你一定注意到了这个简化方案有个代价段落里如果本来混合了多种样式比如一句里有加粗和正常文字、有黑体和宋体重建后整个段落都会变成第一个Run的样式混排信息丢失。但在实际项目里这个代价大多数时候可以接受。原因很简单模板占位符通常单独占一个段落比如【项目名称】、【编制日期】这类本身就是一行独立文字不存在混排需求。如果你的模板必须保留段内多样式那就需要更精细的做法——先找出关键字在完整文本中的起止下标映射回对应的Run索引区间只清理这个区间内的Run把替换结果写进起始Run区间外的Run保持原样。这个延伸实现留给读者按需补全核心API就是runStartIndex和runEndIndex的映射实现难度不高但代码量会明显增加。3.4 正文之外的表格与页眉页脚遍历模板不只是正文段落我处理的模板里第一页有标题段落中间有一张参数表表内单元格也有占位符页眉还挂了项目编号。所以替换逻辑必须覆盖三个维度正文段落、正文表格、页眉页脚。完整入口函数public static void ReplaceAll(XWPFDocument doc, Dictionarystring, string replacements) { // 正文段落 foreach (XWPFParagraph para in doc.Paragraphs) { ReplaceInParagraph(para, replacements); } // 正文表格 foreach (XWPFTable table in doc.Tables) { ReplaceInTable(table, replacements); } // 页眉 foreach (XWPFHeader header in doc.Headers) { foreach (XWPFParagraph para in header.Paragraphs) { ReplaceInParagraph(para, replacements); } foreach (XWPFTable table in header.Tables) { ReplaceInTable(table, replacements); } } // 页脚 foreach (XWPFFooter footer in doc.Footers) { foreach (XWPFParagraph para in footer.Paragraphs) { ReplaceInParagraph(para, replacements); } foreach (XWPFTable table in footer.Tables) { ReplaceInTable(table, replacements); } } } private static void ReplaceInTable(XWPFTable table, Dictionarystring, string replacements) { foreach (XWPFTableRow row in table.Rows) { foreach (XWPFTableCell cell in row.GetTableCells()) { foreach (XWPFParagraph para in cell.Paragraphs) { ReplaceInParagraph(para, replacements); } // 处理嵌套表格 foreach (XWPFTable innerTable in cell.GetTables()) { ReplaceInTable(innerTable, replacements); } } } }如果你用的NPOI版本较老没有doc.Headers/doc.Footers属性那得升到2.5以上或者绕道解压包内word/header1.xml手动处理。我的建议是直接升版本别在这个地方浪费时间。3.5 输出保存与换行、特殊字符处理替换完成后把文档写出去就简单了using (FileStream output new FileStream(outputPath, FileMode.Create, FileAccess.Write)) { doc.Write(output); }但有两个细节得提醒。第一个是换行符。如果替换后的内容里包含\n直接写进同一个RunWord打开后经常表现得很诡异有的版本显示成空格有的版本显示成小方块。我的做法是替换值里发现换行就把文本按换行拆成多个部分每个部分分别SetText行与行之间调用run.AddCarriageReturn()。这样Word才能正确识别为段落内换行或非正式换行。第二个是XML特殊字符。关键字或替换值里如果包含、、这类字符NPOI的SetText内部会做XML转义一般不用你操心。但有一种情况会翻车从外部配置读取替换值时如果文件编码不是UTF-8比如读GB2312编码的CSV中文会直接变成乱码再写进docx。所以读取外部数据源时要么统一转成UTF-8要么显式指定编码方式读取。4. 实测踩坑记录三类真实故障的完整排查4.1 替换后无效果的排查占位符被拆散成多个Run现象很简单替换程序跑完没有任何报错新文档打开一看【项目名称】还是原样躺在那里日志里甚至搜不到关键字未找到的输出——因为它压根没觉得需要找。排查过程走了弯路我一开始怀疑是模板里的占位符名称写错了于是打开word/document.xml直接搜【项目名称发现它确实存在。但注意看XML结构时发现这个占位符被格式拆分成了两个Run中间还夹着一个样式变更节点。为了彻底看透这个问题我写了个辅助函数把段落里每个Run的文本带索引打出来private static void DumpParagraphRuns(XWPFParagraph para) { StringBuilder sb new StringBuilder(); for (int i 0; i para.Runs.Count; i) { sb.Append(i) .Append(: [) .Append(para.Runs[i].GetText(0)) .Append(]\n); } Debug.Log(sb.ToString()); }打印结果一目了然第0个Run文本是【项目第1个Run文本是名称】字体从宋体变成了黑体。也就是说用户编辑模板时把占位符分成了两段格式不同的文本Word老实巴交地存成了两个Run。这之后我把替换逻辑全部升级为段落级判定也就是第3章的方案。从那以后不管模板来源多复杂只要视觉上是连续的文本都能稳定替换。4.2 文件损坏的排查Word域与普通占位符混用这个坑比较深排查过程也更曲折。现象是替换完成后生成的docx偶发性地用Word打开提示文件损坏是否尝试恢复。第一步我先去掉了所有含百分号的替换内容故障消失于是怀疑和%相关。但后来又试出只含百分号不含其他内容时故障也不一定会触发这才意识到问题不在字符本身而在模板里占位符周边的结构。进一步定位发现模板里很多东西是用Word的域功能做的。域功能生成的是一组结构化XML节点fldChar、instrText、separate、t等它们共同组成一个域对象。在外观上用户看到的就是【项目名称】这一行字但内部结构完全不同。NPOI的Run遍历能看到其中的文本片段可当你直接用SetText修改某个Run的内容很可能把域的结构语义破坏掉Word打开时就认为文件结构不合法要求恢复。排查清楚之后修复方案很直接模板里禁止用Word的域来当占位符。如果业务方拿来的模板已经用了域先在Word里全选占位符区域把它们转为纯文本再进Unity流程。从这以后模板里不准出现域直接写进了模板制作规范。4.3 平台与文件锁问题IL2CPP裁剪、流未释放、中文路径这一节攒了三个小坑每个都不大但遇到了都很磨人。第一个是Android真机替换失效。Windows编辑器模式跑得无比顺畅打Android包后一跑就抛异常报的是MissingMethodException或TypeLoadException。排查栈信息后发现指向NPOI内部类型加载失败最后锁定IL2CPP裁剪。解决办法就是第2.2节的link.xml配置保留后重打包验证通过。第二个是连续生成第二次报文件正在被另一个进程使用。原因是模板读取的FileStream没有及时释放第一次用完还占着句柄。修复方式是所有流操作都用using包裹输出文件名也尽量用时间戳或GUID保证唯一。第三个是中文路径问题。输出目录里带中文在某些非中文系统区域设置的机器上FileStream创建会失败。我的处理是程序内所有中间路径统一用英文最终文件放到用户选择的英文目录如果业务必须中文文件名用Path.Combine拼接并且确保目录提前存在避免目录不存在这种隐性问题。5. 模板规范化与批量生成的项目经验5.1 好模板的三个标准踩过这些坑之后我总结出一套好模板的标准直接写进了模板交付规范。第一占位符尽量单独成段不要和常规文字混排。因为跨Run合并的简化方案会重建整个段落如果该段落只有占位符重建后格式丢失在视觉上几乎没有影响如果占位符混在一句话中间重建后整句格式被统一用户一眼就能看出不对劲。第二占位符标志选择要足够安全。我推荐【】或者{{ }}这种组合不要用单个#或避免和正文里的普通符号冲突导致误替换。替换字典的Key也要避免正则特殊字符不然在文本内容里匹配时会出人意料的事故。第三模板里所有占位符尽量统一字体、字号和颜色不要一个占位符内局部加粗、局部变色。这会让Word自动拆分的Run数量达到最小也在很大程度上减少了跨Run问题的发生频率。5.2 批量生成时的性能与并发注意点做批量报告生成时性能瓶颈不在替换逻辑本身而在反复加载模板。如果你要基于同一个模板生成几千份文件每次new XWPFDocument(FileStream)再跑替换光解析模板的时间就会积累成明显开销。我的做法是把模板解析和替换拆成两步。第一步加载模板得到XWPFDocument对象做完所有替换立即写入输出流然后释放下一份文档重新加载模板。看起来简单但能避免一个隐性问题——直接复用同一个XWPFDocument对象连续Write到多个输出NPOI内部的一些索引状态可能残留偶发出现内容串文档的情况。并发方面实测下来不同输出文件的处理可以丢给多个线程并行跑但要注意替换字典在并发读时不要被修改。Dictionarystring, string在只读场景下多线程访问是安全的我可以放心地把处理循环丢进线程池。单份几十KB的模板NPOI单文档替换耗时在几十毫秒到两百毫秒之间1000份文档几分钟跑完完全能接受。5.3 发布前验证清单与工具化思路项目交付前我把验证项整理成了一张清单建议你也照这个思路做一遍检查项具体操作期望结果正文占位符用NPOI读回输出文件并搜索关键字搜不到任何占位符表格占位符用Word打开生成的docx检查表格单元格内容已替换表格框线完整页眉页脚用Word打开检查每一节页眉页眉内容替换正确Android真机IL2CPP打包后跑完整流程无异常且文件可正常打开中文文件名输出路径含中文打开保存正常无路径报错除了清单我还习惯性地做一个小工具函数处理模板之前先打印整个文档的段落、Run、表格层级结构。不要小看这一步它能在替换逻辑真正跑起来之前就把模板里的域、拆分Run、文本框等问题全部暴露出来省掉大量排错时间。我在实际项目里用这套流程跑了几千份模板核心功能一直很稳定。唯一一次线上翻车是业务同事把占位符做进了Word自动域里从那以后模板入库之前必然先跑结构检查工具。如果你准备在Unity里用NPOI做Word关键字替换我的建议是先别急着写替换脚本先写个函数把模板的段落、Run、表格层级打一遍看清结构再动手后面所有问题都会好解决很多。希望这篇踩坑记录能让你少走点弯路。
