Math Olympiad 插件的对抗式证明验证提示词库：从 85.7% 自验证到人类评审级核查的完整 Prompt 体系
2026/9/30 6:41:09
上个月接了个外包需求，客户要求后台点击“导出报名表”，直接下载一份排版好的Word文档。当时我坐在工位上想了五分钟，脑子里把能在PHP里生成Word的方案全过了一遍。我猜你现在搜“php 生成word文档”，多半也是类似的场景：要么给管理系统加导出功能，要么处理合同、报表、录用通知书之类的业务。这篇文章就把我这几年用PHP生成Word的经验摊开讲，包括方案怎么选、代码怎么写、坑在哪里，以及我在实际项目里积累的小技巧，希望对正在做同样事情的人有帮助。
1. 先确定路线：PHP生成Word的三条主流方案怎么选
先说结论：PHP生成Word这事，方案选错了后面全白干。我见过不少同事一上来就查“PHPWord怎么装”，装完才发现客户要的其实是浏览器里能直接打开的Word文件，又或者客户用的Office版本太老，docx打不开，最后只能换方案重写。所以第一步不是写代码，是先把方案选型想清楚。
1.1 方案A：操作本机Office组件（COM机制）
这是老牌做法。在Windows服务器上通过PHP调用COM接口，直接驱动本机安装的Microsoft Word。大致代码如下：
$word = new COM("Word.Application") or die("无法启动Word"); $word->Visible = false; $doc = $word->Documents->Add(); $word->Selection->TypeText("Hello World"); $doc->SaveAs("C:/test.docx"); $word->Quit();这个方案的优点是生成效果和真实Word完全一致，因为本来就是Word本身在干活；缺点也极其明显：只能在Windows上跑，服务器必须装Office，PHP的COM扩展得开着，而且并发一高就很容易出进程卡死。有一天我拿它给客户批量生成一百多份合同，跑到第53份时Word进程直接挂掉，整个目录卡住不动。从那以后我再也没在生产环境用过COM方案。除非你确定服务器是Windows且并发量极低，否则不推荐。
1.2 方案B：HTML转Word
这个思路是把数据渲染成一份带HTML标签的页面，然后把文件后缀改成.doc。用很简单的方式就能验证：新建一个记事本，写几行HTML，另存为xx.doc，双击打开，Word真的能认。
header("Content-type: application/msword"); header("Content-Disposition: attachment; filename=test.doc"); echo "<html><body><h1>标题</h1><p>内容</p></body></html>";这个方案实现成本最低，但问题也很致命：如果你在WPS里打开尚可，放到Microsoft Word里，经常弹“文件格式与扩展名不匹配”的警告；如果你在文档里加了CSS样式，Word解析出来的效果可能完全不对，比如margin失效、表格宽度错乱。所以我把它定位成“应急方案”，适合内部临时导出，不适合给外部客户交付正式文件。
1.3 方案C：用PHPWord直接生成docx
PHPWord是目前PHP社区里最主流的Word生成库，它的本质是生成符合Office Open XML规范的docx压缩包。你不需要理解太深，只需要知道它是由PhpOffice组织维护、社区活跃度高、文档齐全就够了。这也是我目前的主力方案。它天然跨平台，Windows、Linux都能跑，不依赖服务器装Office，生成出来的docx文件可以直接分发。
三条方案对比起来就是下面这张表：
| 对比维度 | COM调用Word | HTML转.doc | PHPWord生成docx |
|---|---|---|---|
| 跨平台 | 仅Windows | 全平台 | 全平台 |
| 依赖服务器安装Office | 必须 | 不需要 | 不需要 |
| 排版精细度 | 高 | 低 | 中高 |
| 并发安全性 | 差 | 好 | 好 |
| 学习成本 | 中 | 极低 | 中 |
| 适用场景 | 本地单机、低并发 | 临时导出 | 绝大多数业务系统 |
1.4 我最终推荐什么
如果你现在还没动手，直接选PHPWord。它不完美，但它是平衡方案复杂度和输出质量的最佳选择。接下来所有内容我都基于PHPWord展开。需要说明的是，这里提到的安装方式和API调用，都是基于社区常见实践的总结，不同版本之间细节可能略有差异，但只要思路对了，版本差异只是查文档的问题。
2. PHPWord实战：从安装到产出一份可交付的文档
选好方案就得动手。这一节我按实际流程走一遍：装环境、写第一份文档、用模板替换动态内容、处理中文排版。每一步我都会说明为什么这么做。
2.1 环境准备：关于PHP版本、扩展和Composer
PHPWord是标准Composer包，安装前你只需要确认环境满足三点：PHP版本在7.4以上（新版甚至要求8.0以上）、开启了ext-zip扩展（因为docx本质是zip包）、以及Composer可用。很多人会用phpstudy升级php版本或是在Docker里跑PHP，这些方式我都试过，只要把Composer配好就行，没有特殊门槛。
composer require phpoffice/phpword这一步完成后，vendor目录里就会出现phpoffice/phpword。如果你用的是ThinkPHP、Laravel这类框架，直接在框架里引入Composer自动加载，然后在控制器里use PhpOffice\PhpWord\PhpWord;即可。这里有一个小经验：很多新手在框架外裸写PHP时容易忘掉require vendor/autoload.php，导致报“Class not found”错误。裸写时代码开头务必加上这一行。
2.2 创建第一份Word文档：三段式代码结构
PHPWord的代码结构非常固定，核心只有三步：新建文档对象、往里添加内容、保存输出。我用一个最简单的公告示例说明：
require 'vendor/autoload.php'; use PhpOffice\PhpWord\PhpWord; use PhpOffice\PhpWord\IOFactory; $phpWord = new PhpWord(); // 添加一个节（section），相当于Word里的一页 $section = $phpWord->addSection([ 'paperSize' => 'A4', 'marginTop' => 1000, // 单位是twip，1厘米约等于567 twip 'marginBottom' => 1000, 'marginLeft' => 1400, 'marginRight' => 1400, ]); // 标题：居中、加粗、字号16 $section->addText('关于系统升级维护的通知', [ 'bold' => true, 'size' => 32, // 注意：size单位是半磅，32即16号字 'name' => '微软雅黑', ], ['align' => 'center']); // 正文：首行缩进、字号12 $section->addText('尊敬的用户：', ['size' => 24, 'name' => '宋体']); $section->addText('为了提供更稳定的服务，系统将于本周六凌晨进行升级维护……', [ 'size' => 24, 'name' => '宋体', ], ['indent' => ['firstLine' => 480]]); // 保存为docx文件 $fileName = 'notice.docx'; $phpWord->save($fileName, 'Word2007');这里最容易被新手忽略的是单位问题。PHPWord里字体size单位是半磅，32表示16pt；页边距单位是twip，1440 twip等于1英寸。我第一次用的时候直接填了size => 16，生成出来的字小到没法看，后来查文档才知道要把磅数乘以2。这种细节恰恰是实际开发中会耽误时间的地方。
2.3 用模板替换实现动态数据：效率和规范性兼顾
上面的写法适合内容完全代码控制的场景，但业务中更常见的需求是：客户给了一个现成的Word模板（带红头、印章位置、固定表格），我们只需要把数据库里的数据填进去。这种情况不要用addText重画模板，而是用PHPWord的TemplateProcessor。
use PhpOffice\PhpWord\TemplateProcessor; $templatePath = './template/contract.docx'; $templateProcessor = new TemplateProcessor($templatePath); // 模板里写的是 ${name}、${date} 这类占位符 $templateProcessor->setValue('name', '张三'); $templateProcessor->setValue('date', date('Y-m-d')); $templateProcessor->setValue('amount', '12,500.00'); $outputPath = './output/contract_' . date('YmdHis') . '.docx'; $templateProcessor->saveAs($outputPath);模板替换的最大好处是格式由人工预先排好，程序只负责填数据，生成的文档几乎不会出现格式错乱。我需要提醒你的是：占位符一定要在模板里用普通文本写，不要在文本框里写；不要把${name}拆成两段，Word有时会自动把单词拆到两行，导致替换失败；如果替换后出现奇怪的空格，检查模板里是不是混了全角空格。这些看起来都是小事，但都真实发生在我接过的项目里。
2.4 段落样式与中文排版：字体名要写对
在PHPWord里设置中文字体，有人会纠结“为什么设置了宋体，Word里显示的还是默认字体”，原因在于Word和WPS对字体名的识别有一定差异，而且addText的第三个参数控制的是段落格式，字体设置必须放在第二个参数里。另外name其实可以直接填中文字体名，不用转英文。实践中我的标准写法是：
$section->addText('正文内容', [ 'name' => '宋体', 'size' => 24, 'color' => '333333', ]);如果你需要全文统一风格，可以直接使用addTitleStyle定义标题样式，或者直接操作$phpWord->addFontStyle()注册一个字体样式，后面所有addText直接引用样式名就行。这点类似CSS里的类名，比每段都写一遍样式参数干净得多。
3. 深入表格、图片、页眉页码：把文档做到接近人工排版
生成纯文字文档并不难，难的是客户需要表格、图片、页眉页脚和页码。这一节我把这几类常见需求逐一拆开讲。
3.1 表格：从创建到填充数据
表格在合同、报价单、报名表里出现频率极高。PHPWord创建表格的逻辑是先建表格对象，再逐行逐单元格填充内容：
$table = $section->addTable([ 'borderSize' => 6, 'borderColor' => '999999', 'cellMargin' => 80, ]); // 表头 $table->addRow(); $table->addCell(2000)->addText('姓名', ['bold' => true, 'size' => 21]); $table->addCell(2000)->addText('部门', ['bold' => true, 'size' => 21]); $table->addCell(2000)->addText('入职日期', ['bold' => true, 'size' => 21]); // 数据行 $data = [ ['张三', '技术部', '2023-06-01'], ['李四', '产品部', '2022-11-20'], ]; foreach ($data as $row) { $table->addRow(); foreach ($row as $cellText) { $table->addCell(2000)->addText($cellText, ['size' => 21]); } }注意addCell方法的第一个参数是单元格宽度，单位也是twip，2000约等于3.5厘米。如果你想实现合并单元格，可以使用gridSpan：
$cell = $table->addCell(6000, ['gridSpan' => 3]); $cell->addText('这是一行合并单元格的内容');这个gridSpan相当于是列合并。行合并则需要用vMerge，逻辑上是把上下两个单元格设置为vMerge的restart和continue。我建议你遇到复杂表格时先画一个表格草稿，标清楚哪些格子要合并，再对应写代码，否则很容易在逻辑里绕晕。另外我再给一个实际经验：给表格的每个单元格设置固定宽度时，建议所有行的同一列宽度保持一致，否则Word打开后表格会整体乱掉。
3.2 图片：本地图和动态生成的图都能插入
合同里常常要插入签名、盖章，报名表里可能要插入证件照。PHPWord插入图片用的是addImage方法：
$section->addImage( './upload/sign.png', [ 'width' => 100, 'height' => 50, 'alignment' => 'center', ] );这里的宽高单位是像素，但底层会自动换算。如果你的图片特别大，建议先用PHP的GD库压缩后再插入，否则生成的docx体积会膨胀得很厉害。我做过一个项目，用户上传了一张5MB的照片，直接插入Word后整个docx达到8MB，邮件附件都发不出去，后来加了压缩逻辑才降到300KB。这个点在后面“结合热搜需求的延伸实战”里我还会再展开。
3.3 页眉页脚与页码：别再一个劲找API了，用Footer
页眉页脚的需求在正式文书里几乎是标配。PHPWord里的实现方式很简单：
$section = $phpWord->addSection(); // 页眉 $header = $section->addHeader(); $header->addText('XX公司内部资料', ['size' => 18, 'name' => '微软雅黑']); // 页脚（含页码） $footer = $section->addFooter(); $footer->addPreserveText('第 {PAGE} 页 / 共 {NUMPAGES} 页', ['size' => 18]);这里有个很特别的点：页码必须用addPreserveText，而不是addText。{PAGE}和{NUMPAGES}是域代码，会被Word识别成自动页码。我第一次用addText试图把{PAGE}写进去，结果文档里出现了一行纯文本{PAGE}，客户当场发截图过来问是什么情况。另外，如果你是分多个addSection生成文件，每个section都要单独添加页眉页脚，否则第二部分起就没有页码了。
3.4 目录、超链接和书签：一般够用，但别求完美
PHPWord支持目录功能，用起来是这样：
$section->addTOC();但它生成的是域代码形式的目录，Word打开后需要右键“更新域”才能显示具体目录内容，不是自动填充的。如果你遇到“word文档窗口三级标题变二级标题格式不对”这类问题，其实不是PHP的锅，是Word打开文档后的标题级别映射问题，通常和模板里使用了自定义样式有关。我的建议是：目录最好让客户在Word里手动更新，程序侧保证标题用标准的Heading 1、Heading 2样式即可。超链接用$section->addLink('https://example.com', '官网')，书签相对冷门，用到时查官方文档即可，这两个一般项目里不多见。
4. 实际项目里最容易踩的五个坑和排查过程
这块是我最想分享的。代码写多了你会发现，生成Word的技术难点不在怎么调用API，而在出错之后的排查思路。下面几个坑全部来源于真实项目，我把当时的排查链路写出来，方便你以后直接跳过。
4.1 中文字体乱码：问题不在地图炮，而在编码和字体名
坑的现象是：文档打开后中文字正常，但偶尔出现“锟斤拷”或空白方块。我之前排查这个花了大半天，最后定位出两个独立原因。第一个原因是PHP文件本身不是UTF-8编码，导致addText写入的字符串是GBK字节流，docx内部却是UTF-8 XML，最终乱码。这个排查很快，用编辑器看文件右下角编码就清楚了。第二个原因是字体缺失，把name设为电脑里不存在的字体，Word会做字体替换，某些特殊字体替换后就成了方块。我的固定方案是：全项目统一用UTF-8无BOM编码，字体只用宋体、微软雅黑、黑体这类全平台通用字体。如果你生成后发给别人打开就乱码，而你本地正常，优先怀疑字体缺失。
4.2 模板变量替换失败：占位符里藏着不可见字符
有次做批量录用通知书，模板里写的是${name}，替换后几十份文件里只有个别文件替换失败，打开一看还是${name}原样。我用十六进制编辑器检查模板文件，发现模板里${name}和${之间藏了一个看不见的软换行符。原因是客户在Word里手动编辑时，本来完整的占位符被自动换行拆开了，Word在不可见位置插入了控制字符。排查办法很简单：在Word里打开模板，按Ctrl+Shift+8显示所有格式标记，确保占位符在一行内完整无半角空格和换行。如果模板是从别人手里拿来的，这个检查步骤绝对不能省。
4.3 表格行高与分页错乱：把“固定值”改成“最小值”
这个问题出现在一个商品报价单项目里。生成后的表格第一页底部露出一行字，第二页顶部又露半行字，怎么看怎么别扭。当时我以为是分页符的问题，查了半天分页方法，结果真正原因是单元格高度设置成了固定值，文字稍微多一点就被截断。解决办法是不要给行高设置固定值，只设置表格的cellMargin和控制列宽，让行高自动适应内容。如果确实要设置行高，用tblHeader属性让表头在跨页时自动重复：
$table->addRow(null, ['tblHeader' => true]);加了这个之后，表格分页时表头会自动出现在新页面顶部，这个细节在正式合同里非常加印象分。
4.4 doc与docx兼容性：老客户机器打不开怎么办
还有一个高频场景：客户单位的电脑还在用Word 2003，他们只能打开.doc，打开.docx会出现格式不兼容的提示。PHPWord默认保存的是docx格式，如果要兼容旧版本，有两种办法。一是用PHPWord的Word97格式保存，但新版PHPWord对Word97支持并不总是完善，实测中部分样式会丢失；二是把docx用LibreOffice批量转换成doc，前提是服务器装了LibreOffice：
libreoffice --headless --convert-to doc output.docx --outdir /output我目前的经验是：新项目直接用docx，不迁就旧版；老项目实在无法沟通时，才用LibreOffice做格式转换。还有一点是另存后的文件命名，文件下载时注意设置正确的Content-Type和文件名后缀，否则浏览器可能把Word文件当HTML打开。下面这段是我常用的下载响应头：
header('Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document'); header('Content-Disposition: attachment; filename="' . urlencode($fileName) . '"'); readfile($outputPath);4.5 服务器生成慢：性能瓶颈多半在循环插入图片
最后一个是性能问题。批量生成几百份Word文档时，如果每份文档都要插入大量图片，速度会慢到让人抓狂。我实测过，一次生成200份带签章的合同，直接在循环里反复addImage，耗时超过120秒，PHP默认执行时间直接超时。后来我做了两个优化：图片全部提前压缩成相同尺寸，而且只压缩一次；改用模板替换方式，模板里已经有图片，程序只填文字。优化后耗时降到25秒，完全够用。这里也体现了选模板替换方案的另一层价值。
5. 结合热搜需求的延伸实战：文本处理与图片生成
在搜“php 生成word文档”的过程中，我注意到很多人同时会搜相关的文本处理、图片生成、验证码识别、正则提取等需求。这些其实都可以在生成文档前或生成过程中串起来用，我举几个典型例子简单展开说明，供有类似需求的读者参考。
5.1 金额小写转大写：给合同金额加一道保险
做合同时，金额常常要先显示阿拉伯数字，再显示中文大写，这是财务规范要求。PHP里实现小写转大写并不复杂，下面是一个常见的实现思路：
function numToRmb($num) { $c1 = '零壹贰叁肆伍陆柒捌玖'; $c2 = '分角元拾佰仟万拾佰仟亿'; $num = round($num, 2) * 100; if (strlen($num) > 15) return '金额太大'; $str = ''; if ($num == 0) return '零元整'; $num = strval($num); $len = strlen($num); for ($i = 0; $i < $len; $i++) { $n = intval(substr($num, $i, 1)); $j = $len - $i - 1; if ($n == 0 && $j != 0 && $j != 2) { if ($str && substr($str, -1) != '零' && substr($str, -1) != '元') { $str .= '零'; } } else { $str .= mb_substr($c1, $n, 1) . mb_substr($c2, $j, 1); } } return $str . '整'; }这段代码的思路是把金额放大100倍转成整数，按位匹配中文单位。实际项目里我用它生成合同附件中的金额列表，生成后再用PHPWord写入Word。需要注意的是：浮点运算会有精度误差，转大写前最好先用round($num, 2)对金额做一次标准化，否则可能出现“1.005”这类转出来多一分钱的问题。
5.2 用GD库动态生成图片再插入Word
在报名表场景里，常常需要给每个人生成一张带二维码的报名凭证。我的做法是先用PHP的GD库生成二维码图片，再调用addImage把它写入Word指定位置。GD库生成图片的逻辑不复杂，代码略长，我强调三个关键点：一是服务器必须安装gd扩展，二是生成临时图片后及时删除，避免堆积，三是生成时设置好imagepng的清晰度，保证扫描能识别。二维码内容一般包含一个URL或唯一ID，生成前记得对内容做URL编码。如果你觉得GD库写起来麻烦，也可以直接用现成的二维码库先生成图片文件，再交给PHPWord插入，两者效果一样。
5.3 正则表达式与文本清洗：把脏数据洗干净再填文档
做文档导出时，最大的工作量往往不是写Word代码，而是清洗数据。比如数据库里导出的手机号可能是["13800138000","13900139000"]这种带引号和括号的格式，直接放进文档里非常不专业。这时候正则提取就能派上用场：
$input = '["13800138000","13900139000"]'; preg_match_all('/\d{11}/', $input, $matches); $phones = $matches[0]; // $phones => ['13800138000', '13900139000']同理，如果需要从一段混合文本里提取金额、身份证号、日期，都可以用正则先做清洗，再交给Word模板填充。我习惯在进入生成流程之前，先写一个数据预处理函数，把所有字段统一做一次trim和格式校验，宁可多花十分钟清洗，也不要让脏数据直接出现在客户拿到的合同里。
5.4 一个必须提醒的安全配置：别把PHP文件直接暴露在公网
既然搜索引擎把“php伪协议”“文件包含漏洞”“php反序列化漏洞”这些词带到了这个话题旁边，我在这里多说一句安全方面的防御性提醒。生成Word文档的PHP脚本如果有文件读取、模板下载功能，在公网部署时要特别注意两点：一是配置文件里关闭allow_url_include，避免远程文件包含类的安全隐患；二是对用户上传的任何文件做后缀和白名单校验，不要直接使用用户传入的模板路径。我的做法是模板统一放在受保护的目录内，按ID映射，不接受外部路径参数。另外，如果下载功能不需要登录，建议加一个一次性token校验，防止被批量调用消耗服务器资源。这些都是常规的防御性配置，不是攻击方法，只是希望你在给客户交付时把安全底线守住。
最后再分享一个个人习惯：我几乎所有项目里都会单独封装一个WordExporter类，内部统一处理模板加载、变量替换、文件命名、下载响应。后续无论做合同还是做报表，只需要调一个方法传入数据数组。这样写看似前期多花一点时间，但后续需求一变，改起来非常省事。你如果只是临时用一次，可以直接按上面的代码来；如果打算长期维护，建议也抽一层封装，相信我，三个月后的你会感谢现在的自己。