ARM架构M2 Mac运行官方Puppeteer Docker镜像失败求助

API 探路者

2026-7-26

问题

在Mac Pro M2（ARM架构）设备上运行Docker容器，使用Puppeteer官方示例脚本生成PDF时，浏览器进程启动失败，报错信息如下：

/home/pptruser/node_modules/puppeteer-core/lib/cjs/puppeteer/node/BrowserRunner.js:300
            reject(new Error([
                   ^

Error: Failed to launch the browser process!
[0328/092440.661398:ERROR:stack_trace_posix.cc(811)] Failed to parse the contents of /proc/self/maps
[0328/092441.259449:ERROR:stack_trace_posix.cc(811)] Failed to parse the contents of /proc/self/maps
[0328/092441.338372:ERROR:stack_trace_posix.cc(811)] Failed to parse the contents of /proc/self/maps
[0328/092441.306294:FATAL:zygote_main_linux.cc(162)] Check failed: sandbox::ThreadHelpers::IsSingleThreaded(). 
#0 0x004007d22f72 base::debug::CollectStackTrace()
#1 0x004007d0f4b3 base::debug::StackTrace::StackTrace()
#2 0x004007c61fbf logging::LogMessage::~LogMessage()
#3 0x004007c62b1e logging::LogMessage::~LogMessage()
#4 0x004007c4bb07 logging::CheckError::~CheckError()
#5 0x0040071bdfaf content::ZygoteMain()
#6 0x0040071b7296 content::RunZygote()
#7 0x0040071b8222 content::RunOtherNamedProcessTypeMain()
#8 0x0040071b90cf content::ContentMainRunnerImpl::Run()
#9 0x0040071b607a content::RunContentProcess()
#10 0x0040071b6606 content::ContentMain()
#11 0x0040077a02cf headless::HeadlessShellMain()
#12 0x0040038d7255 ChromeMain
#13 0x004010fa5d0a __libc_start_main
#14 0x0040038d702a _start

qemu: uncaught target signal 5 (Trace/breakpoint trap) - core dumped
[0328/092441.393397:FATAL:zygote_main_linux.cc(162)] Check failed: sandbox::ThreadHelpers::IsSingleThreaded(). 
#0 0x004007d22f72 base::debug::CollectStackTrace()
#1 0x004007d0f4b3 base::debug::StackTrace::StackTrace()
#2 0x004007c61fbf logging::LogMessage::~LogMessage()
#3 0x004007c62b1e logging::LogMessage::~LogMessage()
#4 0x004007c4bb07 logging::CheckError::~CheckError()
#5 0x0040071bdfaf content::ZygoteMain()
#6 0x0040071b7296 content::RunZygote()
#7 0x0040071b8222 content::RunOtherNamedProcessTypeMain()
#8 0x0040071b90cf content::ContentMainRunnerImpl::Run()
#9 0x0040071b607a content::RunContentProcess()
#10 0x0040071b6606 content::ContentMain()
#11 0x0040077a02cf headless::HeadlessShellMain()
#12 0x0040038d7255 ChromeMain
#13 0x004010fa5d0a __libc_start_main
#14 0x0040038d702a _start

qemu: uncaught target signal 5 (Trace/breakpoint trap) - core dumped
[0328/092441.928094:ERROR:bus.cc(399)] Failed to connect to the bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory
Received signal 11 SEGV_MAPERR 40cf3900b8200008
#0 0x004007d22f72 base::debug::CollectStackTrace()
#1 0x004007d0f4b3 base::debug::StackTrace::StackTrace()
#2 0x004007d22a01 base::debug::(anonymous namespace)::StackDumpSignalHandler()
#3 0x004010078140 <unknown>
#4 0x004008e8a678 FcCharSetSerializeAlloc
#5 0x004008e9914c FcValueListSerializeAlloc
#6 0x004008e990a1 FcPatternSerializeAlloc
#7 0x004008e90e80 FcFontSetSerializeAlloc
#8 0x004008e87390 FcDirCacheBuild
#9 0x004008e8d083 FcDirCacheScan
#10 0x004008e8d120 IA__FcDirCacheRead
#11 0x004008e82567 FcConfigAddDirList
#12 0x004008e824b2 IA__FcConfigBuildFonts
#13 0x004008e91641 IA__FcInitLoadConfigAndFonts
#14 0x004008e819d1 FcConfigInit
#15 0x004008f215e4 base::NoDestructor<>::NoDestructor<>()
#16 0x004008f20ded gfx::GetGlobalFontConfig()
#17 0x004005d8708d content::BrowserMainRunnerImpl::Initialize()
#18 0x00400dd68bcb headless::HeadlessContentMainDelegate::RunProcess()
#19 0x0040071b7ed2 content::RunBrowserProcessMain()
#20 0x0040071b931d content::ContentMainRunnerImpl::RunBrowser()
#21 0x0040071b90f3 content::ContentMainRunnerImpl::Run()
#22 0x0040071b607a content::RunContentProcess()
#23 0x0040071b6606 content::ContentMain()
#24 0x0040077a01fa headless::HeadlessShellMain()
#25 0x0040038d7255 ChromeMain
#26 0x004010fa5d0a __libc_start_main
#27 0x0040038d702a _start
  r8: 000020b8003a0000  r9: 0000000000000002 r10: 0000000000000e00 r11: 000020b8002578a8
 r12: 0000004001eb4dd0 r13: 000000000000000e r14: 000020b8003b90a0 r15: 0000000000000000
  di: 000020b8003a0000  si: 000000000001c000  bp: 00000040100238d0  bx: 000020b800257880
  dx: 0000007d03d309cc  ax: 40cf3900b8200000  cx: 000000000000003c  sp: 00000040100238a0
  ip: 0000004008e8a678 efl: 0000000000000206 cgf: 002b000000000033 erf: 0000000000000004
 trp: ffffffffffffffff msk: 0000000000000000 cr2: 40cf3900b8200008
[end of stack trace]
qemu: uncaught target signal 11 (Segmentation fault) - core dumped


TROUBLESHOOTING: https://pptr.dev/troubleshooting

    at onClose (/home/pptruser/node_modules/puppeteer-core/lib/cjs/puppeteer/node/BrowserRunner.js:300:20)
    at Interface.<anonymous> (/home/pptruser/node_modules/puppeteer-core/lib/cjs/puppeteer/node/BrowserRunner.js:288: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.15.0

使用的测试脚本如下（已添加Docker适配配置）：

/**
 * Copyright 2017 Google Inc. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

'use strict';

const puppeteer = require('puppeteer');

(async () => {
    const browser = await puppeteer.launch(
        {
            headless: true,
            args: [
                '--no-sandbox',
                '--disable-setuid-sandbox',
                '--disable-dev-shm-usage',
                '--disable-gpu'
            ]
        }
    );
    const page = await browser.newPage();
    await page.goto('https://news.ycombinator.com', {
        waitUntil: 'domcontentloaded',
    });
    // page.pdf() is currently supported only in headless mode.
    // @see https://bugs.chromium.org/p/chromium/issues/detail?id=753118
    await page.pdf({
        path: 'hn.pdf',
        format: 'letter',
    });

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

原因与解决方案

核心原因

问题本质是ARM架构与x86镜像的兼容性冲突：

Mac Pro M2为ARM64架构，若使用x86/amd64版本的Puppeteer/Docker镜像，Docker会通过qemu模拟x86环境运行，但Chromium在模拟环境下会触发沙箱、线程检测等兼容性故障，导致进程崩溃。
报错中的Check failed: sandbox::ThreadHelpers::IsSingleThreaded()和qemu相关提示，直接指向架构模拟的兼容性问题。

解决步骤

使用ARM64架构的官方Puppeteer镜像
直接采用官方提供的ARM兼容镜像，避免架构模拟：

# 拉取ARM64版本的官方镜像
docker pull puppeteer/puppeteer:latest

运行容器时挂载本地脚本目录，执行脚本：

docker run --rm -v $(pwd):/home/pptruser/work puppeteer/puppeteer:latest node work/your-script.js

调整Puppeteer启动参数
在现有脚本中追加ARM架构适配参数，绕过线程检测与兼容性问题：

const browser = await puppeteer.launch({
    headless: 'new', // 启用新版无头模式，稳定性更强
    args: [
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--disable-dev-shm-usage',
        '--disable-gpu',
        '--disable-software-rasterizer', // 禁用软件光栅化，适配ARM架构
        '--single-process' // 强制单进程模式，绕过线程检测失败问题
    ]
});

自定义Dockerfile时指定ARM架构
若需构建自定义镜像，需明确使用ARM64基础镜像：

# 使用ARM64架构的Node基础镜像
FROM node:18-bookworm-slim

# 安装ARM版本的Chromium及依赖
RUN apt-get update && apt-get install -y chromium

# 指定Puppeteer使用的Chromium路径
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

CMD ["node", "your-script.js"]

构建时指定平台：

docker build --platform linux/arm64 -t your-puppeteer-image .

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

ARM架构M2 Mac运行官方Puppeteer Docker镜像失败求助

问题 #

原因与解决方案 #

核心原因 #

解决步骤 #

问题

原因与解决方案

核心原因

解决步骤