1 篇博文 含有标签「mPDF」

在商品页点击 PDF 目录下载时，页面先弹出 WordPress 的 "There has been a critical error on this website"；把缺库问题修完，同一个端点又改报 HTTP 500——三个独立的坑，排成了同一条故障链。

在开发 CCLEE B2B（WooCommerce B2B 增强插件，覆盖企业用户管理、差异化定价、批量下单）的 PDF 目录下载功能时，三个坑挨个踩了一遍。

TL;DR​

三个坑共享一个背景：CI + rsync 的容器化部署链路。排完这条链的插件，在任何标准 LAMP 环境都不会复现——它们几乎全是容器化与 REST 上下文的组合产物。

场景一：下载报 "There has been a critical error"——vendor 没上服务器​

现象：本地一切正常，部署后点下载即见 WordPress 通用致命错误页。

根因：vendor/（mPDF 库）没到服务器。链路是双重的：插件自己的 .gitignore 排除了 /vendor/；仓库根 .gitignore 又有 vendor/ 与 plugins/ 两条规则，即使文件被跟踪也会被顶层规则遮蔽。CI 的 checkout 跳过未跟踪文件，rsync 如实镜像了一个缺库目录，服务器上 require_once vendor/autoload.php 直接 Fatal。

修复：插件 .gitignore 移除 /vendor/，仓库根添加例外规则，再强制提交：

git add -f wp/plugins/cclee-b2b/vendor/

WordPress 插件走 CI + rsync 部署时，服务器不会执行 composer install——vendor 必须当作源码的一部分进 git。

场景二：wp eval 正常、REST 端点 500——admin 函数缺席​

现象：vendor 齐了之后，wp eval 直接调 PDF 生成方法一切正常；REST 端点 /wp-json/cclee-b2b/v1/pdf-catalog 却返回 500。

根因：两处不兼容 REST 上下文的调用。wp_tempnam() 定义在 wp-admin/includes/file.php——REST 请求不加载这个目录，调用即 Fatal；WC()->shop_management 也非 WooCommerce 公开属性，fallback 路径一触发同样 Fatal。wp eval 不触发，恰恰因为 CLI 加载了包含 admin 文件的完整 WordPress。

修复：admin 函数加存在性判断并给原生兜底：

$tmp = function_exists( 'wp_tempnam' )
	? wp_tempnam( $filename )
	: tempnam( sys_get_temp_dir(), 'pdf' );

店铺名改走公开 API：get_bloginfo( 'name' )。REST 上下文里，任何 wp-admin/includes/ 下的函数都当不存在来写。

场景三：依赖齐了仍 500——mPDF 临时目录不可写​

现象：类加载正常、代码不再 Fatal，REST 依然 500。服务器 access log 只留下一行 858 字节的响应。

根因：mPDF 默认用 vendor/mpdf/mpdf/tmp/ 当临时目录；rsync 保留源机器属主 UID 1001，容器内 PHP-FPM 以 www-data（UID 82）运行，目录不可写，mPDF 构造函数抛异常。容器里想 chown 补救，卷挂载的文件系统又不允许。

修复：构造时显式指定临时目录到系统 /tmp：

$mpdf_tmp = sys_get_temp_dir() . '/mpdf';
if ( ! is_dir( $mpdf_tmp ) ) {
	wp_mkdir_p( $mpdf_tmp );
}

$mpdf = new \Mpdf\Mpdf( array(
	'mode'    => 'utf-8',
	'format'  => 'A4',
	'tempDir' => $mpdf_tmp,
) );

排查这类 500 有个捷径：wp eval-file 直接调用内部方法，绕过 REST 路由与权限检查，异常堆栈一步到位。同类静默坑在 WooCommerce 定制里不止一处——PPCP 按钮静默跳过是另一例。

常见问题​

为什么 wp eval 能跑、REST 端点却 500？​

CLI 环境加载完整 WordPress（含 wp-admin/includes/），REST 请求不加载这个目录。依赖 admin-only 函数（如 wp_tempnam）的代码在 wp eval 下一切正常，进 REST 就 Fatal Error——两个上下文装载的文件集不同。

怎么快速定位 REST 500 背后的具体异常？​

用 wp eval-file 直接调用插件的内部方法，绕过 REST 路由与权限检查，异常堆栈一步到位；比在 REST 响应里只看到一个 858 字节的 500 页面高效得多。

容器化部署 WordPress 插件要在服务器上跑 composer install 吗？​

不要指望它——CI + rsync 部署链路里服务器不会执行 composer install，vendor 目录必须进 git、随 rsync 落到服务器。插件自己的 .gitignore 若排除了 /vendor/，部署出的插件就是缺库的。

第三方库自带的临时目录为什么在容器里不可写？​

rsync 同步时保留源机器的属主 UID（如 1001），容器内 PHP-FPM 以另一身份运行（如 www-data 的 82），vendor 内的默认临时目录随之不可写；容器卷挂载的文件系统还常常不允许 chown。显式把 tempDir 指到 sys_get_temp_dir() 即可。