Vercel部署Next.js API启动Chromium报libnss3.so缺失如何解决

架构老林

2026-8-28

问题原因

报错提到的libnss3.so是Chromium运行必需的系统共享库，本地开发正常、Vercel生产环境触发错误的核心原因：

你代码中引用的chrome-aws-lambda已停止维护，其内置的Chromium版本仅适配旧版Amazon Linux运行时，Vercel当前默认的Node.js 18/20运行时基于新版Amazon Linux 2023，缺少该老版本Chromium匹配的底层系统依赖，无法直接启动进程。
若将全量puppeteer作为生产依赖安装，Vercel构建阶段会自动裁剪冗余文件，很容易把Chromium依赖的共享库剔除；且全量Puppeteer自带的Chromium是为通用Linux环境编译的，没有针对Serverless环境做依赖适配和体积优化，直接运行也会触发缺库错误。

修复步骤

第一步：卸载不兼容的旧依赖，安装适配Vercel最新运行时的Chromium包
先执行命令移除旧依赖：

npm uninstall puppeteer chrome-aws-lambda puppeteer-core

安装生产环境需要的适配版Chromium和Puppeteer核心包，全量Puppeteer仅装到开发依赖供本地调试使用：

npm install @sparticuz/chromium puppeteer-core
npm install -D puppeteer

第二步：替换浏览器实例初始化代码，移除废弃的chrome-aws-lambda引用
将原有获取浏览器实例的代码替换为以下实现，自动区分本地和生产环境：

import chromium from '@sparticuz/chromium';
import puppeteerCore from 'puppeteer-core';

async function getBrowserInstance() {
  const isProduction = process.env.NODE_ENV === 'production';

  if (!isProduction) {
    // 本地开发环境使用本地安装的全量Puppeteer
    const puppeteer = await import('puppeteer');
    return puppeteer.default.launch({
      args: chromium.args,
      headless: true,
      defaultViewport: {
        width: 1280,
        height: 720
      },
      ignoreHTTPSErrors: true,
      ignoreDefaultArgs: ['--disable-extensions']
    });
  }

  // 生产环境使用适配Serverless的Chromium
  return puppeteerCore.launch({
    args: [
      ...chromium.args,
      '--hide-scrollbars',
      '--disable-web-security',
      '--no-sandbox',
      '--disable-setuid-sandbox'
    ],
    defaultViewport: {
      width: 1280,
      height: 720
    },
    executablePath: await chromium.executablePath(),
    headless: chromium.headless,
    ignoreHTTPSErrors: true,
    ignoreDefaultArgs: ['--disable-extensions']
  });
}

第三步：配置Vercel函数参数，避免运行资源不足
在项目根目录新建或修改vercel.json，给对应API路由分配足够运行内存，同时配置最长超时时间（路径根据你实际的API目录调整，App Router对应app/api/**/*.{js,ts}，Pages Router对应pages/api/**/*.{js,ts}）：

{
  "functions": {
    "app/api/**/*.ts": {
      "maxDuration": 30,
      "memory": 1024
    }
  }
}

第四步：确认API路由运行时为Node.js
如果你用Next.js App Router，必须在对应的API路由文件顶部声明使用Node.js运行时，Edge Runtime不支持启动Chromium这类二进制进程：

export const runtime = 'nodejs';
export const maxDuration = 30;

完成以上步骤后重新推送到Vercel触发构建即可，新版@sparticuz/chromium会自动处理Vercel环境的依赖加载、临时目录权限问题，不会再出现共享库缺失的报错。

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