cPanel部署Node.js应用无法使用Puppeteer生成PDF的方案咨询

你遇到的报错核心原因是cPanel共享主机默认缺少Chromium运行所需的系统级共享库，且绝大多数cPanel环境不开放root权限让用户安装这类系统依赖，这也是你尝试对应issue里的方案全部失效的根本原因——你没法在无root权限的前提下补齐所有Chromium依赖，不用在原生puppeteer的配置上继续耗时间。

方案1：使用便携版Chromium适配无root环境（最适配现有流程，零渲染差异） #

这个方案不需要改动你现有的业务流程，渲染引擎和本地Chrome完全一致，且直接输出PDF Buffer，完美匹配后续流上传需求：

• 先卸载当前安装的全量puppeteer，执行命令：npm uninstall puppeteer
• 安装两个依赖包：npm i puppeteer-core @sparticuz/chromium
  • puppeteer-core是puppeteer的核心调用层，不会自动下载带依赖的完整Chromium，体积更小
  • @sparticuz/chromium是专门为无root服务器环境打包的便携版Chromium，内置了所有必需的共享依赖，不需要手动安装libatk、libnss之类的系统库，可直接在cPanel环境运行
• 调整浏览器启动代码如下，直接输出PDF Buffer：

const puppeteer = require('puppeteer-core');
const chromium = require('@sparticuz/chromium');

async function htmlToPdfBuffer(htmlContent) {
  const browser = await puppeteer.launch({
    args: [...chromium.args, '--no-sandbox', '--disable-setuid-sandbox'],
    defaultViewport: chromium.defaultViewport,
    executablePath: await chromium.executablePath(),
    headless: chromium.headless,
    ignoreHTTPSErrors: true,
  });
  const page = await browser.newPage();
  // 等待页面所有资源加载完成再转PDF，避免样式缺失
  await page.setContent(htmlContent, { waitUntil: 'networkidle0' });
  // 直接返回Buffer，无需写入临时文件，可直接对接流上传逻辑
  const pdfBuffer = await page.pdf({ 
    format: 'A4', 
    printBackground: true,
    margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' }
  });
  await browser.close();
  return pdfBuffer;
}

方案2：cPanel存在二进制执行限制时的替代方案 #

如果cPanel的安全规则直接禁止用户运行自定义二进制文件，上述方案无法生效，可以把HTML转PDF的逻辑拆为独立的轻量云函数部署：

• 利用你当前使用的云服务商的函数计算能力部署转码逻辑，这类服务原生提供完整的Chromium运行环境，不需要手动配置依赖
• 你的主业务流程只需要把ejs渲染好的HTML内容传给云函数，云函数返回PDF Buffer后直接走原有流上传逻辑即可
• 同云服务商内部的函数调用延迟极低，不会明显增加业务耗时，同时渲染一致性完全有保障

• 不要再尝试html-pdf、node-pdf-generator这类依赖老旧渲染引擎的包，这类包的内核和Chrome差异极大，你基于Chrome规则写的ejs模板必然会出现样式错位，且大部分包长期不维护，适配新Node.js版本也会有问题
• 不要手动上传Chrome二进制到cPanel目录再配置路径，cPanel共享主机的系统库版本普遍偏旧，就算你补上了当前缺失的libatk，后续还会陆续出现十多个其他共享库缺失的报错，根本无法补全
• 优先选择直接返回Buffer的PDF生成方案，避免写入临时文件再读取的操作，既能减少IO耗时，也能规避cPanel环境下的文件权限问题

内容的提问来源于stack exchange，提问作者Ravi Keshri