macOS下Docker运行Puppeteer v19.10.1遇Sandbox不可用错误

问题场景 #

在macOS上通过Docker运行Puppeteer脚本时，执行以下两类命令均报错：
带--cap-add=SYS_ADMIN参数的命令：

docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "$(cat coremakepdf.js)"

不带--cap-add=SYS_ADMIN参数的命令：

docker run -i --init --rm ghcr.io/puppeteer/puppeteer:latest node -e "$(cat coremakepdf.js)"

所用脚本示例（PDF生成、截图类脚本均触发相同错误）：

const puppeteer = require('puppeteer');

(async () => {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();
    await page.goto('https://developer.chrome.com/docs/puppeteer/get-started/', {
        waitUntil: 'networkidle2',
    });
    await page.pdf({ path: 'developer.chrome.com.pdf', format: 'a4' });

    await browser.close();
})();

错误信息 #

运行时先出现平台不匹配警告，随后触发浏览器启动失败的致命错误：

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

  Puppeteer old Headless deprecation warning:
    In the near feature `headless: true` will default to the new Headless mode
    for Chrome instead of the old Headless implementation. For more
    information, please see https://developer.chrome.com/articles/new-headless/.
    Consider opting in early by passing `headless: "new"` to `puppeteer.launch()`
    If you encounter any bugs, please report them to https://github.com/puppeteer/puppeteer/issues/new/choose.

/home/pptruser/node_modules/@puppeteer/browsers/lib/cjs/launch.js:262
                reject(new Error([
                       ^

Error: Failed to launch the browser process!
[0424/114437.785256:ERROR:stack_trace_posix.cc(811)] Failed to parse the contents of /proc/self/maps
[0424/114437.819230:FATAL:zygote_host_impl_linux.cc(127)] No usable sandbox! Update your kernel or see https://chromium.googlesource.com/chromium/src/+/main/docs/linux/suid_sandbox_development.md for more information on developing with the SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox.
#0 0x004007d22f72 base::debug::CollectStackTrace()
#1 0x004007d0f4b3 base::debug::StackTrace::StackTrace()
#2 0x004007c61fbf logging::LogMessage::~LogMessage()
#3 0x00400647ec16 content::ZygoteHostImpl::Init()
#4 0x0040071b8b23 content::ContentMainRunnerImpl::Initialize()
#5 0x0040071b6427 content::RunContentProcess()
#6 0x0040071b6606 content::ContentMain()
#7 0x0040077a01fa headless::HeadlessShellMain()
#8 0x0040038d7255 ChromeMain
#9 0x004010fa5d0a __libc_start_main
#10 0x0040038d702a _start

qemu: uncaught target signal 5 (Trace/breakpoint trap) - core dumped


TROUBLESHOOTING: https://pptr.dev/troubleshooting

    at Interface.onClose (/home/pptruser/node_modules/@puppeteer/browsers/lib/cjs/launch.js:262:24)
    at Interface.emit (node:events:525:35)
    at Interface.close (node:internal/readline/interface:533:10)
    at Socket.onend (node:internal/readline/interface:259:10)
    at Socket.emit (node:events:525:35)
    at endReadableNT (node:internal/streams/readable:1359:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

Node.js v18.16.0

问题根源 #

1. 架构不兼容：使用的ghcr.io/puppeteer/puppeteer:latest镜像为linux/amd64架构，而macOS主机为linux/arm64/v8（M系列芯片），通过qemu模拟运行时触发兼容性问题。
2. 沙箱机制失效：Chromium依赖的沙箱在模拟环境中无法正常工作，直接导致浏览器启动失败。

解决方案 #

方案1：匹配架构拉取镜像 #

指定arm64架构的Puppeteer镜像，避免qemu模拟带来的问题：

docker run -i --init --rm --platform linux/arm64 ghcr.io/puppeteer/puppeteer:latest node -e "$(cat coremakepdf.js)"

方案2：禁用Chromium沙箱（仅开发环境使用） #

修改Puppeteer启动配置，添加沙箱禁用参数：

const puppeteer = require('puppeteer');

(async () => {
    const browser = await puppeteer.launch({
        args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    const page = await browser.newPage();
    await page.goto('https://developer.chrome.com/docs/puppeteer/get-started/', {
        waitUntil: 'networkidle2',
    });
    await page.pdf({ path: 'developer.chrome.com.pdf', format: 'a4' });

    await browser.close();
})();

运行容器时建议保留--cap-add=SYS_ADMIN参数提升兼容性：

docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "$(cat coremakepdf.js)"

方案3：升级Puppeteer并启用新Headless模式 #

升级到20+版本的Puppeteer，使用对沙箱更友好的新Headless模式：

const puppeteer = require('puppeteer');

(async () => {
    const browser = await puppeteer.launch({
        headless: "new",
        args: ['--no-sandbox', '--disable-setuid-sandbox'] // 若仍有沙箱问题添加此参数
    });
    // 后续业务逻辑不变
})();

环境信息 #

• Puppeteer版本：19.10.1
• Node版本：v18.16.0
• 包管理器：yarn
• 包管理器版本：1.22.19
• 操作系统：macOS（M系列芯片）

内容的提问来源于stack exchange，提问作者Paul Verest on LinkedIn