Puppeteer 本地部署：离线安装与硬件门槛

卷心菜技术创作者 2026-11-04 86 阅读

Puppeteer 是一套用于控制 Chrome 或 Firefox 的 JavaScript API，可在本机完成网页自动化、截图、PDF 和测试。部署离线环境时，重点不是单独安装 Puppeteer，而是准备 Node.js、浏览器程序和项目依赖，并确认目标机器的系统架构与内存余量。

截至 2026-11-04 核对时，Puppeteer 官方仓库要求使用 Node.js 22.12 及以上版本；TypeScript 项目还需要 TypeScript 5.0.1 以上版本，并把类型检查目标设为 ES2022 或更高。现在值得重新核对，是因为现代 npm、pnpm、Yarn、Bun 和 Deno 默认可能阻止依赖安装脚本；如果浏览器没有随安装包下载，Puppeteer 会在运行时才报错。

先决定安装包，还是只装程序库

Puppeteer 官方提供两种安装入口，区别在于安装时是否同时下载兼容的 Chrome：

方式	安装命令	浏览器是否随安装下载	适合场景
完整安装	`npm i puppeteer`	是	第一次使用、希望安装过程自动准备浏览器
轻量安装	`npm i puppeteer-core`	否	已经准备浏览器，或要控制浏览器安装位置
安装后补浏览器	`npx puppeteer browsers install`	手动触发下载	依赖安装脚本被阻止后补救

完整安装适合普通本地开发；离线部署通常还需要把浏览器文件一并带入目标环境。puppeteer-core 只安装程序库，不包含浏览器，必须在启动时明确指定可执行文件路径，因此更适合已经统一管理 Chromium 或 Chrome 的服务器。

官方 README 给出的完整安装命令是：

npm i puppeteer

只安装程序库则使用：

npm i puppeteer-core

如果安装阶段没有下载浏览器，官方给出的补救命令是：

npx puppeteer browsers install

这不是三个必须全部执行的步骤，而是根据已有环境选择：第一次安装可用 npm i puppeteer；已有浏览器时用 npm i puppeteer-core；安装脚本被阻止时再执行 npx puppeteer browsers install，或手动放置浏览器。

离线部署前要准备什么

离线目标机至少要完成三项准备，并且每项都要能在机器上立即确认。

确认 Node.js 版本。运行：
```
node -v
```
输出的主版本和次版本应达到官方要求的 22.12 以上。版本过低时，先从可联网的同架构机器准备对应 Node.js 运行环境，再拷贝到内网。
确认系统架构和浏览器是否匹配。Linux 离线包不能把 x86_64 浏览器直接拿到 ARM64 机器上运行；Windows、Linux、macOS 也不能共用同一份浏览器二进制文件。先在目标机确认操作系统、CPU 架构和 Chromium/Chrome 是否已经存在。
准备项目依赖与浏览器文件。联网机器完成 npm i puppeteer 或 npm i puppeteer-core 后，将 node_modules、浏览器程序和项目源代码一起打包。离线安装前应在联网机器执行一次浏览器安装命令，避免把“依赖装好了但浏览器没下载”的状态带入目标机。

Puppeteer 是 Node.js 库，不是独立桌面应用。官方没有为 CPU、内存或显卡给出固定最低配置，因此不存在一条适用于所有场景的“最低配置表”。实际门槛主要由浏览器实例数量、标签页数量、页面复杂度和是否长期驻留决定。

离线环境的三条安装路径

路径一：联网机安装后整体拷贝

在联网环境进入项目目录，执行：

npm i puppeteer

然后确认浏览器下载步骤已经完成，再把项目目录、Node.js 运行环境以及 Puppeteer 下载的浏览器文件一起复制到离线机。目标机运行项目时，重点检查浏览器路径是否仍指向有效目录。

这种方式对首次部署最省事，缺点是项目依赖和浏览器文件体积较大，而且目标机不需要执行安装命令。

路径二：目标机只安装程序库

如果内网已经统一部署 Chrome 或 Chromium，使用：

npm i puppeteer-core

随后在启动代码中传入 executablePath，把路径指向目标机实际存在的浏览器。puppeteer-core 不会替你寻找或下载浏览器，因此这个参数不能省略；如果路径错误，常见结果是浏览器启动失败，而不是页面脚本报错。

路径三：先装依赖，再补浏览器

现代包管理器可能阻止安装脚本。官方 README 特别说明：安装脚本被阻止时，Puppeteer 不会在安装期间下载浏览器，随后会出现运行时错误。此时先安装依赖，再运行：

npx puppeteer browsers install

在离线机执行这条命令前，需要先准备浏览器安装包或使用内网可访问的包源；完全断网且没有浏览器文件时，不能指望这条命令临时联网下载。

启动代码与成功标志

官方示例的核心启动流程是创建浏览器、打开页面、访问 URL，最后关闭浏览器：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://developer.chrome.com/');
console.log(await page.title());
await browser.close();

把示例改成离线项目时，建议先访问一个本地 HTML 文件，而不是直接访问互联网地址。这样可以区分“浏览器本身无法启动”和“页面网络访问失败”：

import puppeteer from 'puppeteer';
import { writeFile } from 'node:fs/promises';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent('<title>offline-ok</title>');
const title = await page.title();
console.log(title);
await browser.close();

成功时，终端应输出：

offline-ok

如果使用 puppeteer-core，还要在 launch() 中添加实际浏览器路径。若测试页面可以打开、终端出现 offline-ok，说明 Node.js、浏览器、程序库和基本启动链路都正常；之后再接入真实业务页面，才可以判断页面脚本、代理或权限配置是否正确。

常见卡点：先看报错属于哪一层

安装后启动时提示浏览器下载失败

官方 README 对应的根因是安装脚本被包管理器阻止，而不是 Node.js 本身损坏。处理方式是允许 Puppeteer 的安装脚本运行，或者安装完成后执行：

npx puppeteer browsers install

如果目标机完全断网，则应在联网环境提前下载浏览器，再把浏览器目录和依赖一起拷贝。

`npm i puppeteer-core` 后无法启动

puppeteer-core 不会自动下载浏览器。检查 puppeteer.launch() 是否提供了 executablePath，并确认该路径在目标机上真实存在。不要把 puppeteer-core 当成“功能更少的完整安装包”：它省掉了浏览器下载，但把浏览器供应责任交给了部署者。

本地 HTML 能打开，访问外网失败

这通常说明 Puppeteer 和浏览器已经正常工作，故障位于网络、代理、DNS 或证书链。先用目标机自身的浏览器访问同一 URL，再用 page.goto() 测试；这样可以把浏览器启动问题与网络访问问题分开定位。

ARM64 服务器下载了 x86_64 浏览器

这类服务器部署应优先核对浏览器压缩包的文件架构，而不是反复重装 Node.js。Node.js 运行包、Puppeteer 包和浏览器二进制文件必须分别匹配目标系统架构；不能只因为官方示例在 x86_64 或普通 Linux 上成功，就直接推断 ARM64 也能运行。

硬件怎么估：看浏览器并发，不看显卡型号

官方没有公布固定的 CPU、内存和显卡门槛，因此选机器时应采用“浏览器数量 + 任务并发”的判断方式，而不是寻找一个不存在的最低配置数字。

单浏览器、少量标签页、只访问本地页面时，资源消耗通常较低；多实例同时打开复杂网页、长列表或媒体页面时，内存和 CPU 压力会明显增加。Puppeteer 官方示例在任务结束后显式执行 await browser.close()，这说明长期服务应确保浏览器进程被释放。生产环境中若每次请求都创建浏览器却不关闭，最终表现会是内存持续增长、服务变慢甚至被系统终止。

显卡通常不是“能否安装”的第一检查项。除非页面依赖硬件加速、视频处理或特殊图形能力，否则应先确认 CPU、内存、磁盘空间以及目标系统架构。没有官方固定数值时，最可靠的做法是准备一个实际任务做小规模并发测试，并观察浏览器进程是否能正常启动、关闭和释放资源。

延伸入口与部署建议

官方仓库 README 提供了安装、示例代码、API、FAQ、贡献和故障排查入口：

Puppeteer 官方仓库与 README：https://github.com/puppeteer/puppeteer/tree/main#readme
Puppeteer 官方文档主页：https://pptr.dev/
GitHub Actions 文档：https://github.com/features/actions

其中 GitHub Actions 适合持续集成中的自动化测试，不代表 Puppeteer 必须在 GitHub 云端运行；需要完全内网执行时，仍应在本地或内网 CI 节点部署浏览器。实际操作可按“npm i puppeteer 或 npm i puppeteer-core → 准备匹配架构的浏览器 → 运行本地 HTML 测试 → 确认输出 offline-ok → 再接真实任务”的顺序推进。

参考来源

# AI # 知识

评论区

0 条评论

登录后可评论。