html-pdf包在AWS Lambda运行报错，已部署对应layer仍未解决

错误根本原因 #

该报错来自html-pdf包的底层源码，execPdfToBuffer方法尝试读取子进程返回结果中的filename属性时，发现结果为undefined。本质是你配置的phantomjs子进程执行失败，没有返回预期的输出结构，并非上层业务代码的语法错误。
触发该问题的常见原因如下：

• Lambda运行架构与layer中phantomjs二进制的编译架构不匹配：你layer中的二进制是x86_64版本，如果Lambda当前使用的是arm64（Graviton2）架构，二进制无法正常执行，子进程直接闪退
• 你直接覆盖了LD_LIBRARY_PATH环境变量，丢失了Lambda默认的系统库路径，导致phantomjs运行时依赖的系统so文件无法找到
• layer中的phantomjs二进制没有可执行权限，无法启动子进程
• 你当前使用的Lambda Node.js运行时版本过新，和已经停止维护的html-pdf包存在兼容性问题
• 现有代码的错误处理逻辑存在缺陷，pdf.create报错后没有终止流程，仍然尝试读取返回结果

修复步骤 #

1. 修正环境变量配置 #

不要直接覆盖系统环境变量，改为追加路径，避免丢失默认依赖：

// 原有错误写法：process.env.LD_LIBRARY_PATH = "/opt"
process.env.PATH = `${process.env.PATH}:/opt`;
process.env.FONTCONFIG_PATH = "/opt";
process.env.LD_LIBRARY_PATH = `${process.env.LD_LIBRARY_PATH}:/opt`;

2. 补全错误处理逻辑 #

PDF生成报错后直接终止流程，不要继续执行后续的S3上传逻辑：

pdf.create(attachmentFile, options).toBuffer(function (err, res) {
    if (err) {
        console.error('PDF生成失败：', err);
        return reject(err);
    }
    const params = {
        Bucket: <my_bucket_name>,
        Key: `certificate/${empCertificate.candidateName}${empCertificate.certificateID}.pdf`,
        Body: res,
        ACL: 'public-read'
    };
    S3.upload(params, function (err, data) {
        if (err) {
            console.error('S3上传失败：', err, err.stack);
            return reject(null);
        }
        resolve(data.Location);
    });
});

3. 验证Lambda架构与二进制权限 #

• 进入Lambda控制台的函数配置页面，确认运行架构设置为x86_64，和layer中phantomjs的编译架构一致
• 重新打包html-pdf层，给二进制文件加可执行权限：本地打包前执行chmod 755 phantomjs_linux-x86_64后再压缩上传
• 可临时加测试代码验证二进制可用性，在函数入口处添加如下代码，查看运行日志是否能正常输出版本号：

console.log('phantomjs版本：', require('child_process').execSync('/opt/phantomjs_linux-x86_64 -v', {encoding: 'utf8'}));

长期优化建议 #

html-pdf包已经停止维护超过6年，对Node.js 14以上版本的兼容性极差，后续建议替换为更稳定的方案：

• 使用puppeteer-core配合公共Chromium层生成PDF，支持arm64架构，兼容性更好
• 对接AWS原生文档处理服务生成PDF，减少自定义层的维护成本

内容的提问来源于stack exchange，提问作者Nikhil Srivastava