Puppeteer 运行环境与系统要求全解：Node.js、TypeScript、Chrome for Testing 与 Firefox 的安装前提

Puppeteer 运行环境与系统要求全解：Node.js、TypeScript、Chrome for Testing 与 Firefox 的安装前提

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer

本文基于当前 Puppeteer 仓库（puppeteer与puppeteer-core版本均为 25.8.0）的 docs/guides/system-requirements.md 官方指南展开，系统梳理运行 Puppeteer 所需的 Node.js 与 TypeScript 版本基线、Chrome for Testing 与 Firefox 各自的平台/CPU 架构要求、以及安装浏览器压缩包时系统必须具备的解压工具。读完本文，你将能对照清单检查自己的开发与 CI/CD 环境，快速定位并修复“浏览器下载失败”“解压失败”“类型报错”等由环境不满足引发的问题。

需要说明的是，Puppeteer 的功能与运行要求随版本演进而变化，以下所有版本号与限制均以当前仓库实际内容为准，适用于本仓库对应的 Puppeteer v25 系列。

环境要求总览

官方 system-requirements.md 将运行环境划分为三类，任何一类不满足都会导致 Puppeteer 无法正常工作：

前三项在后续章节逐一展开，第四项会结合仓库源码说明其底层实现，帮助你理解为什么“缺少某个命令会导致安装失败”。

Node.js 运行时要求：Node 22.12+

Puppeteer 以 Node.js 官方 LTS 发布节奏为基线，跟随最新的**维护 LTS（maintenance LTS）**版本线演进。当前仓库对运行时的硬性约束直接写在两个发布包的engines字段中：

• packages/puppeteer/package.json#L35-L37："engines": { "node": ">=22.12.0" }
• packages/puppeteer-core/package.json#L35-L37：同样为"engines": { "node": ">=22.12.0" }

因此安装前应确认 Node 版本不低于 22.12.0：

node --version

在低于该版本的环境中，npm install puppeteer会被包管理器标记为engine不兼容（是否硬性阻止取决于包管理器的engine-strict等配置）。这类版本要求之所以存在，是因为 Puppeteer 25 的源码构建产物（ESM 模块、类型声明与运行时代码）依赖较新版本 Node 的语法与内置 API 支持。

关于“跟随维护 LTS”的实践含义

Node.js 的发布节奏通常为 Current → Active LTS → Maintenance LTS。Puppeteer 团队的策略是让最低支持版本对齐某一维护 LTS 版本线，因此在 LTS 轮换（新版本进入维护期）后，Puppeteer 的主版本/次要版本更新往往会同步抬高engines下限。升级 Puppeteer 后若npm提示 engine 警告，应检查 Node 是否需要随之升级；同理，长期使用低版本 Node 的项目应固定 Puppeteer 版本，避免跨越式升级引入运行时要求不匹配。

TypeScript 要求：5.0.1+ 与 ES2022

仅在使用 TypeScript 时适用。官方指南要求TypeScript 5.0.1 或更高，并且有一个值得注意的附加条件：

如果你对node_modules中的声明文件也执行类型检查（即关闭skipLibCheck），则必须将编译目标设为ES2022 或更高。

为什么需要 5.0.1+ 与 ES2022

Puppeteer 通过 API Extractor 从源码生成类型声明，puppeteer与puppeteer-core包均暴露统一的 lib/types.d.ts。这些声明引用了较新的 TypeScript 语法与标准库类型（与异步迭代、Disposable/AsyncDisposable、Symbol.dispose等 ES2022+ 能力相关），旧版本 TS 无法解析，旧编译目标下标准库缺少对应类型定义。

仓库自身的工程化配置可作为佐证：根目录 tsconfig.base.json 中target为"ES2022"（第 30 行）、module为"ES2022"（第 11 行），同时开启了"skipLibCheck": true（第 23 行），即仓库默认不检查依赖包（含 Puppeteer 自身）的.d.ts文件。这意味着：

• 保持skipLibCheck: true（TypeScript 默认值）时，普通项目只需 TS 版本满足 5.0.1+ 即可使用 Puppeteer 类型；
• 若你的项目出于某种原因关闭了skipLibCheck、对所有node_modules类型做全量检查，则必须同步把target抬到 ES2022 或更高，否则会命中 Puppeteer 声明中的新语法/类型而报错。

参考配置示例：

{ "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "bundler", "skipLibCheck": false } }

需要说明：仓库根 package.json 的devDependencies中 TypeScript 为 6.0.3（第 204 行），高于指南中的 5.0.1+ 下限，说明 Puppeteer 自身已在更新的 TS 版本上完成构建与校验；5.0.1+ 是面向使用方的兼容基线。

Chrome for Testing 浏览器要求：平台与架构

安装puppeteer包时会通过其postinstall脚本（见 packages/puppeteer/install.mjs，由 packages/puppeteer/package.json 的"postinstall": "node install.mjs"触发）自动下载 Chrome for Testing 及chrome-headless-shell。根据 docs/guides/installation.md，下载体积约 macOS 170MB、Linux 282MB、Windows 280MB，自 v19.0.0 起默认缓存于$HOME/.cache/puppeteer。

官方系统要求指南对 Chrome for Testing 的操作系统与 CPU 架构做了明确限定：

这意味着在 Linux 的 arm64 架构、或非上述发行版环境中，直接使用自动下载的官方二进制可能不满足前提。从源码结构看，浏览器的下载、元数据与启动由独立的@puppeteer/browsers子包承担（packages/browsers），Puppeteer 25 依赖其 3.2.1 版本（见两个包各自的dependencies）。

Linux 系统库依赖

对 Debian/Ubuntu 与 openSUSE/Fedora，指南要求参考 Chromium 上游仓库维护的依赖清单：

• Debian/Ubuntu 使用.deb体系的 dist 包版本清单（Chromium 源码中的chrome/installer/linux/debian/dist_package_versions.json）；
• openSUSE/Fedora 使用 RPM 体系依赖清单（chrome/installer/linux/rpm/dist_package_provides.json）。

这两份清单本质上是 Chromium 二进制运行所需的系统共享库集合（涉及图形、字体、NSS 安全库、GTK 等桌面/无头运行依赖）。在精简的容器或 CI 基础镜像中，这些库往往缺失，典型表现是运行 Puppeteer 时 Chrome 进程启动即退出或报缺库错误。若需要现成的依赖参考，仓库内提供了一套 Linux 容器方案，可查看 docker/Dockerfile、docker/README.md 与 docs/guides/docker.md。

架构不匹配的排查思路

如果你的机器是 Apple Silicon（arm64）macOS，应使用 arm64 构建的 Chrome for Testing；若在其他非 x64 平台上安装失败，可借助 PUPPETEER_CACHE_DIR 调整缓存目录观察下载产物，或按下文“解压工具”一节排查是否是系统命令缺失所致。更多运行时错误与对应解法见 docs/troubleshooting.md。

Firefox 浏览器要求与 Linux 解压工具

除 Chrome 外，Puppeteer 也支持驱动 Firefox。Firefox 二进制遵循 Mozilla 官方系统要求，同时在 Linux 上有额外工具依赖：

Linux 上解压 Firefox 安装包需要系统提供xz或bzip2命令。

xz 与 bzip2 究竟何时需要：源码给出了精确答案

为什么是“xz 或 bzip2”二选一？从源码看，Puppeteer 依据 Firefox 的大版本号选择归档压缩格式：

packages/browsers/src/browser-data/firefox.ts#L16

return majorVersion >= 135 ? 'xz' : 'bz2';

即 Firefox 135 及以上版本在 Linux 上分发.tar.xz归档，早期版本为.tar.bz2。这与测试用例相互印证：

• packages/browsers/test/src/firefox/firefox-data.test.ts#L28-L32 断言 135 起下载.tar.xz归档；
• packages/browsers/test/src/firefox/install.test.ts#L33 覆盖“下载 bzip2 归档的 buildId”的安装场景。

因此在 Linux 上，如果同时准备测试 Firefox 135+ 与旧版本，最好xz、bzip2都安装；只测试新版本时至少需xz。命令缺失时安装会直接失败，其报错由解压代码抛出（详见下一节）。

解压工具要求与仓库底层实现

Chrome for Testing 的 ZIP 解压链

官方指南原文要求：

Windows 上解压 Chrome for Testing 二进制需要tar.exe或 PowerShell；macOS/Linux 上需要unzip。除非安装了可选的yauzl依赖。

这段要求的实现位于@puppeteer/browsers的 packages/browsers/src/fileUtil.ts。unpackArchive（第 26-59 行）按扩展名分派：.zip走extractZip，.tar.bz2/.tar.xz走extractTar，.dmg走 macOS 的hdiutil挂载拷贝，.exe则静默自解压（Firefox Windows 安装包）。

ZIP 解压采用**“CLI 优先、可选依赖兜底”**的双级策略（fileUtil.ts#L201-L219）：

1. 先尝试系统 CLI：Windows 上依次尝试C:\Windows\System32\tar.exe解压（第 268-272 行），失败后回退powershell.exe（再尝试pwsh.exe）调用Expand-Archive（第 279-301 行）；macOS/Linux 直接调用unzip -o archive -d folder（第 305 行）；
2. 若 CLI 均不存在（进程报ENOENT，见第 307-312 行），则动态import可选的yauzl包（第 224-253 行）；该依赖未安装时抛出ArchiverUnavailableError；
3. 两级都不可用时，抛出错误信息（fileUtil.ts#L216-L218）：

Extraction failed: no zip archiver is available. Install 'unzip' (or 'tar.exe'/Powershell on Windows), or add the optional 'yauzl' dependency.

据此可得出两个实用结论：

• Windows 10 1803+ 自带tar.exe，通常无需额外安装即可完成解压；更老的系统或精简环境才需要 PowerShell/yauzl兜底；
• 想彻底摆脱对系统 CLI 的依赖（例如受限的 CI 沙箱），可在项目中显式安装可选依赖：npm i yauzl，Puppeteer 会优先…不，实际执行顺序是 CLI 优先，仅在 CLI 缺失时才回退到yauzl；因此正确姿势是同时保证 CLI 与yauzl至少其一可用。

tar.xz / tar.bz2 解压链与错误信息

Firefox Linux 归档的解压走extractTar（fileUtil.ts#L118-L158），内部 spawnxz -d或bzip2 -d作为解压器（解压器名称由常量表 internalConstantsForTesting 提供，便于测试注入）。当系统缺少对应命令时，会抛出（第 126-137 行）：

`xz` utility is required to unpack this archive/`bzip2` utility is required to unpack this archive

这一行为有专门的单元测试覆盖：packages/browsers/test/src/fileUtil.test.ts#L182-L214 将xz/bzip2替换为不存在的命令，断言抛出上述错误信息；同时第 117-119 行验证tar.xz正常解包。

各平台解压工具速查表

对应工具一键安装示例（以 Debian/Ubuntu 为例）：

sudo apt-get update sudo apt-get install -y unzip xz-utils bzip2

如何验证环境是否满足要求

按顺序自查，即可覆盖官方 system-requirements.md 的全部要点：

# 1. Node.js 版本 ≥ 22.12.0 node --version # 2. (可选) TypeScript 版本 ≥ 5.0.1 npx tsc --version # 3. 解压工具是否可用（按平台挑对应命令） unzip -v # macOS / Linux xz --version # Linux bzip2 --version # Linux where tar.exe # Windows # 4. 触发浏览器下载与解压，验证完整链路 npx puppeteer browsers install

其中npx puppeteer browsers install会读取 Puppeteer 配置并把对应浏览器下载解压到缓存目录。若此前被包管理器拦截了自动下载脚本，也需要手动执行该命令完成浏览器安装（参见 docs/guides/installation.md 与 docs/troubleshooting.md）。

在 Linux 上进一步确认浏览器能否真正启动（这同时隐式验证了系统库依赖是否齐全）：

node -e "const p = require('puppeteer'); (async () => { const b = await p.launch(); console.log('launched', await b.version()); await b.close(); })()"

注意：若使用puppeteer-core（不自动下载浏览器），系统要求中的“浏览器自动下载/解压”部分不适用，你只需自行准备浏览器并满足 Node/TS 要求；需要连接远程浏览器或自行管理浏览器时选择 puppeteer-core，完整安装策略见 docs/guides/installation.md。

常见问题与定位指引

结合 docs/troubleshooting.md 与上文源码分析，以下问题通常都指向“环境要求未被满足”：

1. 安装阶段报Could not find Chrome (ver. ...)：多为安装脚本被包管理器拦截，浏览器未下载；执行npx puppeteer browsers install即可（详见 installation.md）。
2. **解压阶段报no zip archiver is available或\xz`/bzip2\utility is required**：按上表补齐系统工具，或安装可选依赖yauzl`。
3. Chrome 启动即崩溃或报缺共享库：Linux 系统库不满足 Chrome for Testing 的发行版依赖清单，可参考仓库的 docker/Dockerfile 与 docs/guides/docker.md。
4. TypeScript 对 Puppeteer 类型报错：确认 TS ≥ 5.0.1；若关闭了skipLibCheck，把target设为 ES2022 及以上。
5. 下载位置异常/需要重定位缓存：Puppeteer 自 v19 起默认缓存于$HOME/.cache/puppeteer，可通过环境变量PUPPETEER_CACHE_DIR或配置文件中的cacheDirectory修改（docs/troubleshooting.md）。

总结

Puppeteer 的系统要求可以归结为一条清晰的“软件栈 + 系统工具”检查链：Node.js ≥ 22.12.0 →（可选）TypeScript ≥ 5.0.1 且目标 ES2022+ → 与平台匹配的 Chrome for Testing 架构与 Linux 系统库 → Windows 的tar.exe/PowerShell、macOS/Linux 的unzip、Linux 的xz/bzip2。其中解压工具部分并非文档的纸面约定，而是@puppeteer/browsers中 fileUtil.ts 的真实执行路径——理解这条调用链（CLI 优先、yauzl兜底、按 Firefox 版本选择xz/bzip2），能让你在任何精简环境里都快速补齐依赖。环境就绪后，即可按 docs/guides/getting-started.md 与 docs/guides/configuration.md 开始实际的浏览器自动化开发。

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer