企业官网建设流程全解析

前一段时间接了个内部需求，要求把一套合同生成流程整体迁到Linux服务器上跑。业务方之前的方案是在Windows环境用PHP调用Word COM组件，把模板里的变量替换掉，再借助Office自带的导出能力生成PDF。逻辑听起来没问题，但服务器一换到Linux，COM组件直接没法用了，整条链路瞬间断掉。我当时的第一反应就是改用PhpWord，把整个读取、修改、导出流程统一到一套纯PHP方案里。做完之后回头复盘，这几步链路里的坑比想象中多，尤其是"PHP生成PDF"这个环节，方案选不对，后面全是麻烦。

这篇博文就把整个实现过程拆开讲清楚：从PhpWord的选型逻辑，到模板替换的细节处理，再到Linux下两条主流PDF生成路线的对比和踩坑记录，最后附上我实际用到的一整套代码骨架，以及几个很容易忽略但影响很大的小细节。如果你也在做类似的事情，或者正准备用PHP在Linux下处理Word模板，这篇文章应该能让你少走不少弯路。

1. 为什么是PhpWord：Linux下PHP处理Word文档的选型逻辑

一开始我也想走"简单"路线，继续找能在Linux上替代COM组件的方案。Java那边有成熟的东西，Python也有，但团队技术栈就是PHP，没必要为了一个文档生成功能引入一套新语言和一套新部署体系。当时的候选方案其实就三个：PhpWord、纯OpenXML操作、LibreOffice的UNO API。这三个方案的选型逻辑值得先说一下，因为这会直接影响后面的所有代码结构。

PhpWord是PHPOffice组织下的开源库，纯PHP实现，不依赖任何Office软件，可以通过Composer直接安装，在Linux的LNMP环境里几乎零成本接入。它内部把Word文档抽象成PHP对象，遍历段落、表格、图片、样式都是走统一接口，代码写起来很顺手。它最大的优势是"读取—修改—另存"这条链路是闭环的，能把模板里的内容读取出来修改后重新保存为新的docx，这一条看似基础的能力，实际上很多方案做不到。

纯OpenXML操作是完全绕开库，把docx当成zip压缩包拆开，直接改里面的document.xml，再重新打包回去。这个方案够底层、够灵活，但代价是你要自己维护XML结构，对Word的样式继承、编号定义、域代码这些细节都得非常清楚。改个纯文本没问题，一旦涉及合并单元格、多级列表、页眉页脚里的变量，工作量直接翻几倍。

LibreOffice的UNO API是走服务化方案，服务器上装一个LibreOffice，PHP通过UNO协议调用它去打开Word、改内容、再导出。这个方案转换PDF的能力确实强，但部署链路重，而且LibreOffice对docx的解析也和微软Office存在一些差异，经常出现"本地Windows看着好好的，Linux下LibreOffice一改，格式就变了"的情况。UNO的PHP扩展也不是随手就能装上，编译依赖、版本匹配，每一个环节都够折腾半天的。

最终选PhpWord，核心原因就三条：一是它是纯PHP，和现有技术栈无缝衔接；二是读取修改另存的闭环天然满足模板替换这个核心需求；三是社区活跃，Composer安装方便，遇到问题搜一搜基本都有答案。后面再搭配一个独立的PDF转换工具（下面会详细讲），整条链路就变成"PhpWord负责内容处理，外部工具负责格式转换"，各司其职，出问题也好排查。

2. 模板替换的核心链路：TemplateProcessor的读写机制与占位符设计

PhpWord处理模板替换，靠的是PhpOffice\PhpWord\TemplateProcessor这个类。它的工作方式说白了就是——把docx模板当作一个"填空游戏"：模板里预先写好${字段名}这样的占位符，代码把占位符替换成真实内容，再保存成新文档。这一步看似简单，但里面涉及几个关键机制，理解不到位就会在各种奇怪的地方翻车。

2.1 模板内占位符的命名规则与设计规范

占位符的语法是${字段名}，比如${customerName}、${contractNo}。我实际用的模板里一般会分成几类：

• 纯文本变量：${customerName}、${contractAmount}
• 日期变量：${signDate}、${effectiveDate}
• 数字变量：${contractPeriod}，这类要注意精度和千分位格式
• 图片占位符：这个比较特殊，后面单独说

提示：占位符不要跨行。Word里一个段落如果很长，软换行会被拆成多个run，${customerName}这个字符串可能被拆成两半，TemplateProcessor就替换不了。我在模板里吃过这个亏，后来所有占位符都在一行内写完，绝不手动换行。

命名规范上，我习惯用驼峰式英文，不用中文，不用带空格或特殊符号。因为${}占位符本质上就是字符串匹配，如果命名里有空格，替换逻辑容易各种不对劲，出了问题还得怀疑是不是名字写错了。

2.2 setValue方法的使用细节与多值替换

创建TemplateProcessor对象、读取模板、替换变量、保存新文档，核心代码就这几行：

require_once __DIR__ . '/vendor/autoload.php'; use PhpOffice\PhpWord\TemplateProcessor; $templatePath = '/data/templates/contract_template.docx'; $outputPath = '/data/output/contract_' . time() . '.docx'; $templateProcessor = new TemplateProcessor($templatePath); $templateProcessor->setValue('customerName', '某科技公司'); $templateProcessor->setValue('contractNo', 'HT20240612-001'); $templateProcessor->setValue('signDate', date('Y-m-d')); $templateProcessor->setValue('contractAmount', number_format(128000.50, 2)); $templateProcessor->setValue('contractPeriod', '12个月'); $templateProcessor->saveAs($outputPath); echo "文档已生成：{$outputPath}\n";

多个变量依次调用setValue就可以。底层实现是通过查找模板XML里的${变量名}文本节点，用传入的值替换掉。值里的特殊字符会被自动做XML转义处理（比如&转成&、<转成<），这一点PhpWord内置处理了，不需要自己操心。

但有个细节值得注意：setValue这个名字虽然叫"值替换"，但传进去的内容会被当成纯文本处理。如果你希望替换进去的内容带格式（比如加粗、红色字体、超链接），单靠setValue是无法实现的。这种情况需要把模板做成"一个变量对应一个整段落"，替换时用setComplexValue（配合cast的类型）或者直接改用CLONE块的方式处理。我的实际做法是：对常规文本用setValue，对需要特殊格式的富文本内容，提前在模板里做成多个固定样式段落，代码里整段替换，而不是在文本内部穿插样式，这样样式控制最可控。

2.3 块级替换：cloneRow与cloneBlock处理循环内容

模板替换里最难搞的其实是"重复区域"。比如合同附件清单可能是N行，或者技术方案里有一份动态长度的参数表。如果只靠setValue，这种循环结构根本处理不了。TemplateProcessor提供了两套方法：cloneRow用于表格行复制，cloneBlock用于任意字面段落块复制。

先说表格行复制，这是最常用的：

// 假设模板里有一个表格，第二行是模板行，列里有 ${itemName} ${itemSpec} ${itemQty} $rows = [ ['itemName' => '服务器', 'itemSpec' => '8核16G', 'itemQty' => 2], ['itemName' => '交换机', 'itemSpec' => '48口千兆', 'itemQty' => 4], ['itemName' => '防火墙', 'itemSpec' => '企业级', 'itemQty' => 1], ]; $templateProcessor->cloneRow('itemName', count($rows)); foreach ($rows as $index => $row) { $templateProcessor->setValue('itemName#' . ($index + 1), $row['itemName']); $templateProcessor->setValue('itemSpec#' . ($index + 1), $row['itemSpec']); $templateProcessor->setValue('itemQty#' . ($index + 1), $row['itemQty']); }

关键点是cloneRow的第一个参数是这一行里的任意占位符名字，第二个参数是要克隆的总行数。克隆之后，原来的模板行变成了N行，每一行里同一列的占位符会自动变成${itemName#1}、${itemName#2}这种带编号的形式。然后循环里用#索引去精确替换每一行的内容。这个机制我一开始没理解透，直接在cloneRow之后又去setValue('itemName', ...)，结果只替换了没克隆的那一行，数据对不上，排查了半天才明白。

注意：cloneRow必须在setValue之前调用。顺序反了的话，原占位符已经被替换成真实数据，模板行里找不到可克隆的占位符，克隆出来的行内容就是错的。

再说块级复制cloneBlock。它针对的是非表格场景，比如合同模板里有若干条"付款说明"，每条的结构是一段标题加一段描述。用cloneBlock能把这一段连同格式一起复制N份，再逐份替换。它的调用方式是cloneBlock('blockName', $count)，块首尾用${blockName}和${/blockName}标记包裹。块替换适合结构复杂、无法塞进表格的内容，但使用频率比cloneRow低很多，多数模板场景用表格就够了。

2.4 图片替换：模板图片与动态图片的插入方式

合同里经常要放logo、签名扫描件或资质证书截图。TemplateProcessor处理图片的机制是——模板里先放一张占位图片，然后代码里用setImageValue替换它：

$templateProcessor->setImageValue('signatureImage', [ 'path' => '/data/uploads/signature.png', 'width' => 120, 'height' => 50, 'ratio' => true, ]);

第一个参数是占位图周围的一个可识别文本（模板里需要写${signatureImage}，并且图片本身放在这个标记旁边），后面跟着图片路径和显示尺寸。这里有个坑：模板里如果没放任何图片，直接调用setImageValue不一定生效，因为底层是通过查找模板里已有的图片关系来替换的。所以模板阶段必须放一张任意图片占位，代码里再替换路径。

2.5 保存文件与格式兼容性问题

saveAs保存出来的新文档是标准的docx格式，文件名后缀建议明确写成.docx。如果你把后缀写成.doc，Word和LibreOffice打开时虽然能识别，但会有兼容性警告，而且某些极老的Word版本可能直接打不开。另外，保存路径的目录一定要有写权限，/data/output/这种自定义目录记得chmod 777或者交给www用户，别在根目录或者无权限目录下做保存操作，报错很隐晦，不仔细看日志根本发现不了是权限问题。

提示：如果模板文件本身是.doc（旧版格式），PhpWord不直接支持读取。先把.doc在Windows里统一另存为.docx再作为模板使用。这是最省事的办法，我不建议在Linux环境下去折腾.doc转换，性价比太低。

3. Linux下PHP生成PDF的两条路线：LibreOffice与DomPDF的取舍

这一步是整条链路里最容易出问题的环节。PhpWord本身不生成PDF，官方文档给出的是配合DomPDF的方式，但实际用下来，对复杂Word模板的还原效果并不理想。我在Linux服务器上摸索出了两条可行路线，这里把两条路线的原理、用法、优缺点一次说清楚。

3.1 路线一：PhpWord官方推荐的DomPDF方案

PhpWord库内部支持通过\PhpOffice\PhpWord\Settings::setPdfRenderer()方法来指定PDF渲染器，官方默认支持DomPDF。使用流程是先读取或创建文档对象，然后调用$phpWord->save($outputPath, 'PDF')。它的实现原理是先把Word文档转换成HTML中间格式，再由DomPDF把HTML渲染成PDF。

对简单的、纯文本为主的文档，这条路可以跑通，代码如下：

use PhpOffice\PhpWord\PhpWord; use PhpOffice\PhpWord\Settings; use PhpOffice\PhpWord\IOFactory; // 读取已生成好的docx $phpWord = IOFactory::load($outputDocxPath); // 设置PDF渲染器为DomPDF Settings::setPdfRendererName(Settings::PDF_RENDERER_DOMPDF); Settings::setPdfRendererPath('/your/path/to/dompdf'); // 另存为PDF $phpWord->save($outputPdfPath, 'PDF');

但实际在复杂文档上，问题就来了：

• 样式丢失：Word里的分栏、表格边框、页眉页脚、部分段落缩进，渲染成HTML后大量丢失。
• 中文字体问题：DomPDF对中文字体支持一般，默认字体集里经常找不到中文字体，输出PDF里中文变成方框或空白，需要额外配置中文字体路径和CSS。
• 图片排版错乱：Word里图文混排的效果，转HTML后基本没法保留。

所以DomPDF只适合"文字为主、格式简单、无复杂布局"的场景。如果你的模板里表格占了大半张纸，还有合并单元格和复杂边框，这条路基本走不通。

3.2 路线二：LibreOffice无头模式转换PDF（推荐路线）

我在生产环境最终采用的是LibreOffice方案。LibreOffice是一个开源的办公套件，支持命令行无头模式（headless mode），可以直接把docx文档转换成PDF，转换过程和Word导出PDF的效果非常接近。

服务器上安装LibreOffice：

# CentOS / RHEL 系列 sudo yum install -y libreoffice-writer # Debian / Ubuntu 系列 sudo apt-get install -y libreoffice-writer

注意，libreoffice-writer是仅包含Writer组件的安装包，如果你在最小化服务器上不想装整套LibreOffice（太大），可以只装Writer，能满足docx转PDF的基本需求。如果你还需要处理电子表格或演示文稿，就装libreoffice-calc或libreoffice-impress，按需选择即可。

转换命令非常简单：

soffice --headless --convert-to pdf --outdir /data/output /data/output/contract_xxx.docx

执行后会在--outdir指定的目录下生成同名PDF文件。这条命令我用到生产环境之后非常稳定，复杂表格、页眉页脚、中文字体基本都能正确渲染，比我预期的效果好很多。

但这条路线也有两个需要提前处理的点：

第一，中文字体。Linux服务器上如果没装中文字体，LibreOffice转换时中文会直接变成方块或乱码。解决方法是先检查系统里有没有中文字体：

fc-list :lang=zh

如果列表为空，安装中文字体包（比如fonts-wqy-zenhei、fonts-wqy-microhei），实际上我把常用中文字体都装上了，包括宋体、黑体的开源替代版本：

sudo apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei

第二，运行用户与权限。如果你在PHP的exec()或shell_exec()里执行soffice命令，要考虑运行PHP进程的用户身份。Nginx + PHP-FPM环境下通常是以www-data用户运行，这个用户有没有权限执行soffice、有没有权限在/data/output目录下写文件，都必须在代码上线之前确认好。建议在PHP-FPM的www.conf里把运行用户改成有权限的用户，或者在业务代码里用sudo方式执行命令，但sudo方式有个前提是www-data用户被授权可以无密码执行soffice命令，需要配置/etc/sudoers。

我实际用的PHP调用代码是这样的：

function convertDocxToPdf(string $docxPath, string $pdfPath): bool { $command = sprintf( 'soffice --headless --convert-to pdf --outdir %s %s 2>&1', escapeshellarg(dirname($pdfPath)), escapeshellarg($docxPath) ); exec($command, $output, $returnCode); return $returnCode === 0; }

exec()的返回值不要忽略，$returnCode === 0才表示转换成功。并且建议把$output变量接收住，一旦转换失败，日志里能看到具体原因。

3.3 两条路线的对比与选择建议

为了直观对比，我做了一张表：

结论很清楚：如果你的模板以正式合同、标书、方案这类复杂文档为主，选LibreOffice路线，格式还原度直接决定业务方满意度；如果你只是生成一个简单的确认通知，DomPDF够用但也不是非它不可，我几乎不推荐DomPDF，因为LibreOffice已经把所有功能全包了，装一次之后所有文档都能走它。

4. 实际部署中踩过的坑：字体、权限、缓存与LibreOffice的内部机制

选型选完了，代码也写完了，真正到生产环境跑起来才发现，坑都在你想不到的地方。这一节我把实际遇到的问题一个个列出来，把排查思路讲清楚，后面的人照着排查就行。

4.1 LibreOffice的Profile目录权限问题：为什么PHP执行转换失败但手动执行成功

一个典型的坑：在命令行手动执行soffice --headless --convert-to pdf ...成功，但从PHP的exec()里执行就是失败，返回码非零或者后台没有任何响应。

排查思路是这样的：LibreOffice在运行时会创建一个用户配置文件目录（Profile），默认存放在运行用户的家目录下，路径类似~/.config/libreoffice或~/.libreoffice。当PHP-FPM以www-data用户运行、且www-data的主目录权限异常或不存在，或者目录里之前残留了损坏的配置，就会导致LibreOffice启动报错，转换自然失败。

解决办法常见的有两个：

• 给www-data用户创建主目录并设置正确权限：sudo mkdir -p /var/www && sudo chown www-data:www-data /var/www
• 或者在命令行里通过环境变量指定Profile目录，比如HOME=/tmp，再执行soffice命令。有的项目直接用-env:UserInstallation=file:///tmp/libreoffice_profile参数指定，效果一样。

我实际采用的做法是在soffice命令前拼接环境变量：

$command = 'HOME=/tmp && soffice --headless --convert-to pdf --outdir ' . escapeshellarg($dir) . ' ' . escapeshellarg($docx) . ' 2>&1';

这样就把Profile问题一次性绕过了。

4.2 并发转换时LibreOffice的冲突：统一加锁或固定实例

另一个生产环境常见问题是并发执行多个soffice --headless进程时，可能出现LibreOffice实例冲突或锁文件错误。表现是：一大批量任务同时触发，有的转换成功，有的报Error: source file could not be loaded或者干脆卡住。

这类问题的根本原因是LibreOffice的每个实例都会读写同一个Profile目录，多个进程同时对Profile目录做写操作时就会互踩。解决方案是在PHP侧加一个简单的文件锁，保证同一时间只有一个soffice转换任务在跑：

$lockFile = '/tmp/soffice_convert.lock'; $fp = fopen($lockFile, 'c'); if (!flock($fp, LOCK_EX)) { throw new RuntimeException('获取转换锁失败，请稍后重试'); } try { exec($command, $output, $returnCode); } finally { flock($fp, LOCK_UN); fclose($fp); }

如果并发量很高，也可以换用固定端口的方式启动LibreOffice监听服务，然后通过UNO协议调用，但项目里文件锁已经够用，因为转换任务并发大多在个位数级别。

4.3 转换后PDF内容残缺或空白页的排查顺序

如果你转换出来的PDF出现内容残缺、漏行、空白页，不要直接怀疑LibreOffice本身，先按下面顺序排查：

1. 模板本身是否跨页有虚线框、文本框等复杂元素。LibreOffice对docx里绝对定位的文本框的处理有时偏移，复杂模板建议先用LibreOffice打开人工看一遍，确认模板兼容性。
2. 中文字体缺失。检查fc-list :lang=zh输出，如果没有中文字体就先安装字体。
3. 页边距或纸张大小定义异常。模板里自定义了特殊纸张，LibreOffice可能找不到对应纸张，导致排版错误。
4. 模板里嵌入了外部链接图片。图片如果引用的是本地绝对路径，LibreOffice进程权限不足时读不到图片，就会输出空白占位。

排查时最有效的办法是先把docx转换成PDF，再人工打开PDF对照Word原文件，逐页看问题出在哪。这个过程不能说毫无耐心，因为绝大多数都不是代码bug，而是模板或字体问题。

4.4 一个极容易忽略的问题：PHP的内存限制与执行时间

PhpWord读取大型docx时，尤其文档里图片多、表格大，内存消耗会明显升高。默认的memory_limit=128M经常不够用，我在测试一个带40页内容的方案书模板时就遇到过内存溢出。

建议在调用PhpWord的代码里显式提高内存限制和执行时间：

ini_set('memory_limit', '256M'); set_time_limit(120);

这两个值是经验值，如果你的模板更复杂，调到512M也不夸张。但如果你发现内存消耗异常高，优先检查模板里是不是塞了大量超大尺寸图片，压缩图片后再生成，内存压力会小很多。

提示：soffice进程本身也会占内存，转换大文档时建议给服务器预留至少512M~1G的内存余量。

4.5 字体问题导致的中文乱码：预先统一字体包

中文场景下乱码几乎是必然要遇到的。我在转换一个内容全中文的合同时，第一次输出PDF里所有中文全变成了方块。排查步骤就是上面说的fc-list :lang=zh，一看结果，系统里没装任何中文字体。

装完fonts-wqy-zenhei和fonts-wqy-microhei之后，重新执行转换，中文恢复正常。还有一点，如果你的模板里指定了宋体、黑体这种Windows常见字体名，Linux系统未必有同名字体，LibreOffice会做字体替换。这时候要么在模板里换成Linux已安装的开源字体名，要么在/etc/fonts/下做字体配置文件关联映射，把SimSun映射到文泉驿正黑这类实际存在的字体上。

字体相关的配置我建议一次到位：apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei fonts-noto-cjk，然后fc-cache -fv刷新字体缓存。一套装完，中文字体基本不会有问题。

5. 完整代码骨架与执行流程：从模板读取到PDF输出一条龙

写到这里，把整套代码骨架结构梳理出来，可直接参考改造。我按执行顺序分成模板准备、PHP处理、PDF转换、结果检查四个阶段。

5.1 模板准备阶段的规范操作

模板文件放在/data/templates/contract_template.docx。设计模板时有几条实操建议我总结成了清单：

• 占位符全部单行书写，不跨行、不跨表格cell。
• 所有变量在模板里用${}包围，例如${customerName}。
• 需要循环输出的表格行，预留一行模板行，里面放占位符，这一行永远只保留一行。
• 图片区域放一个临时小图，旁边写${signatureImage}，代码里用setImageValue替换。
• 模板文件保存为.docx，不用.doc。

5.2 PHP处理阶段完整示例

<?php require_once __DIR__ . '/vendor/autoload.php'; use PhpOffice\PhpWord\TemplateProcessor; class ContractGenerator { private string $templatePath; private string $outputDir; public function __construct(string $templatePath, string $outputDir) { $this->templatePath = $templatePath; $this->outputDir = $outputDir; } public function generate(array $contractData): string { $outputDocx = $this->outputDir . '/contract_' . date('YmdHis') . '.docx'; $outputPdf = str_replace('.docx', '.pdf', $outputDocx); $templateProcessor = new TemplateProcessor($this->templatePath); // 基础变量替换 $templateProcessor->setValue('customerName', $contractData['customerName']); $templateProcessor->setValue('contractNo', $contractData['contractNo']); $templateProcessor->setValue('signDate', $contractData['signDate']); $templateProcessor->setValue('contractAmount', number_format($contractData['contractAmount'], 2)); // 循环表格行替换 $items = $contractData['items'] ?? []; $templateProcessor->cloneRow('itemName', count($items)); foreach ($items as $index => $item) { $rowNum = $index + 1; $templateProcessor->setValue("itemName#{$rowNum}", $item['name']); $templateProcessor->setValue("itemSpec#{$rowNum}", $item['spec']); $templateProcessor->setValue("itemQty#{$rowNum}", $item['qty']); } // 图片替换（如果有签名图） if (!empty($contractData['signaturePath'])) { $templateProcessor->setImageValue('signatureImage', [ 'path' => $contractData['signaturePath'], 'width' => 120, 'height' => 50, 'ratio' => true, ]); } $templateProcessor->saveAs($outputDocx); return $outputDocx; } }

5.3 PDF转换与结果校验

<?php function convertToPdf(string $docxPath, string $outputDir): string { $command = sprintf( 'HOME=/tmp && soffice --headless --convert-to pdf --outdir %s %s 2>&1', escapeshellarg($outputDir), escapeshellarg($docxPath) ); $lockFile = '/tmp/soffice_convert.lock'; $fp = fopen($lockFile, 'c'); if (!flock($fp, LOCK_EX)) { throw new RuntimeException('获取LibreOffice转换锁失败'); } $output = []; $returnCode = -1; try { exec($command, $output, $returnCode); } finally { flock($fp, LOCK_UN); fclose($fp); } if ($returnCode !== 0) { throw new RuntimeException('PDF转换失败：' . implode("\n", $output)); } $pdfPath = str_replace('.docx', '.pdf', $docxPath); if (!file_exists($pdfPath) || filesize($pdfPath) === 0) { throw new RuntimeException('PDF文件未生成或为空'); } return $pdfPath; }

调用主流程：

$generator = new ContractGenerator('/data/templates/contract_template.docx', '/data/output'); $docxPath = $generator->generate($contractData); $pdfPath = convertToPdf($docxPath, '/data/output'); echo "生成成功：{$pdfPath}\n";

5.4 目录权限与运行环境核对手册

上线部署前，建议按下面这个清单逐项检查一遍，能省掉大部分"为什么跑不起来"的问题：

5.5 运行效果评估与进一步优化

这套方案上线后，生成一份常规合同的时间大约在2~4秒（大头在LibreOffice启动转换），对比之前Windows环境COM方式，速度基本相当。稳定性上，线上跑了几个月的合同生成任务，没有出现过一次转换卡死或文件损坏，整体是可靠的。

如果后续对转换性能有更高要求，可以从两个方向优化：一是把LibreOffice部署成常驻服务，避免每次启动的开销；二是在高并发场景下引入消息队列，把转换任务串行化处理，既避免并发冲突，又能削峰。但从当前业务量看，这两个优化暂时用不上，文件锁已经足够。

6. 一些实际使用中的补充心得

写到这里，整套方案的技术细节讲得差不多了。最后补充几个我在实际使用中踩出来的、零散但很实用的小经验。

第一，模板文件的备份与版本管理。生产用的模板文件一定要纳入版本管理，每次改动模板前先复制一份备份。因为模板一旦被改坏，线上文档生成会全部受影响，而且这种问题不像代码报错那样有明确的错误堆栈。我有一次就是在一个模板里不小心把${}写成了${ }，多了一个空格，所有字段替换全部失效，排查了好几个小时才找到，教训够深刻。

第二，LibreOffice转换PDF后，文件名不要包含中文或特殊字符。Linux下虽然中文文件名没问题，但个别版本的LibreOffice在转换带中文路径的docx时偶尔会报路径错误，我的做法是内部文件名统一用英文或数字命名，业务展示名在下载时再动态映射成中文，这样最稳妥。

第三，关于setImageValue，不同版本的PhpWord在参数细节上略有差异。我用的是较新的版本，ratio参数能保持图片宽高比。如果你用的是老版本，可能要手动算好宽高。升级库版本时，最好用一份标准的测试文档把整套链路回归一遍，别只看"能跑"就上线，转换类功能最怕暗处的样式差异。

第四，如果业务方要求生成的PDF必须可以被编辑（比如还需要填字段、加备注），LibreOffice转换出来的PDF默认是静态的，不支持表单填写。要实现可编辑PDF表单，需要在模板里用DocVariable之类的特殊域代码，PhpWord对这类域的支持目前不是特别完善，建议单独评估，不要硬塞进现有链路里。

第五，整个链路里最容易忽略监控的地方是soffice进程本身。我加了一个定时脚本，每分钟检查是否有僵死或长时间挂起的soffice进程，超过一定时间就强制杀掉并记录日志。线上环境跑久了，这类兜底手段比代码本身更能保证稳定性。

这篇文章从选型讲到代码，再讲到生产环境踩坑，覆盖了在Linux下用PHP处理Word模板并生成PDF的完整脉络。整体思路就是：PhpWord负责内容处理和模板替换，LibreOffice负责格式还原和PDF转换，两者配合，既保证了灵活性，也保证了输出质量。如果你正准备做类似的功能，希望这篇能帮你避开我踩过的那些坑，让整套流程一次跑通。