Firebase云函数中Puppeteer启动浏览器超时排查求助

一、Puppeteer启动超时问题解决 #

Firebase云函数是无服务器环境，Puppeteer默认配置不适配，按以下调整：

• 强制无头模式+禁用沙箱：云函数没有完整浏览器沙箱，必须加这些启动参数，同时用新版无头模式更稳定：

  const browser = await puppeteer.launch({
    headless: 'new',
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage', // 解决/dev/shm空间不足导致的启动失败
      '--disable-gpu', // 云函数无需GPU加速
      '--single-process' // 减少资源占用，适配无服务器环境
    ]
  });
  

• 改用puppeteer-core：完整版Puppeteer自带的Chromium在云函数环境可能解压或加载出错，换成puppeteer-core，直接用云函数预装的Chromium：

  const puppeteer = require('puppeteer-core');
  const browser = await puppeteer.launch({
    executablePath: '/usr/bin/chromium-browser', // Firebase云函数内置Chromium路径
    // 加上上面的args配置
  });
  

• 匹配Node.js与Puppeteer版本：Firebase云函数的Node.js runtime版本要和Puppeteer兼容，比如Node.js 18对应Puppeteer 19+，版本不兼容会直接导致启动失败。
• 延长函数超时时间：云函数默认超时60秒，浏览器启动+PDF生成可能不够，在firebase.json里调整：

  {
    "functions": {
      "runtimeOptions": {
        "timeoutSeconds": 120
      }
    }
  }
  

二、CORS错误解决 #

Firebase云函数不会自动处理CORS，必须手动在响应里加头：

• 在云函数中添加CORS配置：

  exports.generatePDF = functions.https.onRequest(async (req, res) => {
    // 生产环境建议替换成你的前端域名，不要用*
    res.set('Access-Control-Allow-Origin', '*');
    res.set('Access-Control-Allow-Methods', 'GET, POST');
    res.set('Access-Control-Allow-Headers', 'Content-Type');
  
    // 处理OPTIONS预检请求，直接返回204
    if (req.method === 'OPTIONS') {
      res.status(204).send('');
      return;
    }
  
    // 后续PDF生成逻辑
    try {
      // 生成PDF的代码...
      res.status(200).send(pdfBuffer);
    } catch (err) {
      res.status(500).send(err.message);
    }
  });
  

• 前端请求规范：POST请求要设置Content-Type: application/json，避免触发预检请求失败。

三、额外排查点 #

• 查看云函数日志：在Firebase控制台的函数日志里，找Chromium启动的具体错误信息，比如依赖缺失（不过Firebase已经预装了Chromium所需依赖，大概率是配置问题）。
• 本地模拟器测试：用firebase emulators:start启动本地环境，测试Puppeteer是否能正常运行，排除线上环境的特殊限制。

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