Puppeteer 安装完全指南自动下载机制、puppeteer 与 puppeteer-core 的选型及常见坑位排查【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本文依据 Puppeteer 官方文档 docs/guides/installation.md 展开围绕「如何把 Puppeteer 装进你的项目」这一主题覆盖一条命令快速安装、安装期自动下载 Chrome 的底层机制、现代包管理器拦截安装脚本时的处理方案以及puppeteer与puppeteer-core两个发行包的本质区别与选择依据。读完你将能独立完成安装、按需切换两种包、用配置文件和环境变量精确控制浏览器下载行为并解决诸如Could not find Chrome (ver. ...)之类的经典报错。快速开始一条命令完成安装Puppeteer 是面向 Chrome 与 Firefox 的 JavaScript 自动化 API。在项目中使用它只需要一条命令npm i puppeteer这条命令做的事情远不止「拉取 npm 依赖」这么简单——安装结束后它还会在postinstall阶段触发一次浏览器下载详见下文「安装时到底发生了什么」。因此绝大多数场景下你不需要单独安装浏览器装完即可直接puppeteer.launch()上手。需要注意的是本文讨论的是完整产品包puppeteer的安装路径。仓库中两个发行包的元数据分别位于 packages/puppeteer/package.json 与 packages/puppeteer-core/package.json后者是前者在编译期的直接依赖之一当前版本为puppeteer-core: 25.8.0。安装时到底发生了什么浏览器自动下载机制postinstall 钩子与下载入口在 packages/puppeteer/package.json 的scripts中可以看到一行关键配置postinstall: node install.mjs也就是说每次执行npm i puppeteer含后续的重新安装npm 都会自动运行 packages/puppeteer/install.mjs。该脚本通过动态import(puppeteer/internal/node/install.js)拿到内部安装器并调用其导出的downloadBrowsers()如果 Puppeteer 本体尚未构建比如你直接从源码仓库运行而未先 build它会打印提示并安全退出不会让安装流程崩溃。真正的下载逻辑位于 packages/puppeteer/src/node/install.ts先调用getConfiguration()读取配置文件与环境变量见下文「用配置与环境变量精确控制下载」若配置了skipDownload直接跳过并打印**INFO** Skipping downloading browsers as instructed.否则用detectBrowserPlatform()探测当前平台把浏览器安装到默认缓存目录Chrome、chrome-headless-shell、Firefox 三个下载任务通过Promise.allSettled并发执行全部下载并解压完成后统一打印成功信息避免成功日志插进进度条中间只要有一个任务失败就会抛出提示建议用npx puppeteer browsers install重试或用npx puppeteer browsers clear清理未完成的缓存后重试。会下载什么Chrome for Testing chrome-headless-shell根据 docs/guides/installation.md 的说明安装puppeteer时默认会自动下载一个较新版本的 Chrome for TestingChrome 官方专门为自动化测试发布的构建不与你的日常 Chrome 冲突体积约为 macOS 170MB、Linux 282MB、Windows 280MB一个chrome-headless-shell二进制自 Puppeteer v21.6.0 起引入它是独立于完整 Chrome 的专用 headless 运行载体与 Puppeteer 的版本是保证兼容的。从 packages/puppeteer/src/node/install.ts 的实现可以进一步确认每个浏览器的目标版本优先级是「配置里的version→ 当前发行版内置的PUPPETEER_REVISIONS[browser]→latest」随后通过resolveBuildId()解析出具体的构建号再调用puppeteer/browsers的install()完成下载与解压puppeteer/browsers同样是puppeteer的直接依赖。下载到哪里默认缓存目录浏览器默认被下载到$HOME/.cache/puppeteer该默认自 Puppeteer v19.0.0 起生效后续所有项目共用这一全局缓存避免重复下载。提示如果浏览器因某些原因未随安装下载也可以用 CLI 手工补装。详见 docs/api/puppeteer.configuration.md 对Configuration接口的完整定义以及 docs/guides/configuration.md 的配置指南。自动下载可能被包管理器拦截现象与解决方案:::caution自动下载可能被拦截许多现代包管理器默认禁止依赖执行安装脚本install scripts包括采用了新版 npm RFC 行为的 npm、pnpm、Yarn Berry、Bun、Deno。如果你的包管理器被配置为拦截这些脚本那么安装puppeteer时自动下载就会被静默跳过运行时抛错Could not find Chrome (ver. ...).:::这是因为「下载浏览器」这件事恰好跑在postinstall阶段见上文 packages/puppeteer/package.json而这类脚本正是各家包管理器默认收紧的对象。文档给出两种解决办法方案一安装后手动补装浏览器npx puppeteer browsers install该命令会读取与postinstall完全一致的配置来源把未下载的浏览器补下到位。它本质上就是在手动重放安装期的下载流程因此也是「修改下载相关配置后让其生效」的官方推荐方式见 docs/guides/configuration.md。方案二对 Puppeteer 重新开启 postinstall 脚本以 npm 为例在package.json中加入{ allowScripts: { puppeteer: true } }即可让 npm 在执行安装时允许puppeteer的安装脚本从而恢复自动下载。pnpm、Yarn Berry 等包管理器也有各自等效的「白名单」配置项。puppeteer vs puppeteer-core装哪个、怎么选自 v1.7.0 起官方每个版本都会同时发布两个 npm 包文档反复强调要区分清楚它们的定位——这不是同一份代码的换皮而是「产品」与「库」的本质差异。维度puppeteerpuppeteer-core定位产品product面向开箱即用的浏览器自动化库library面向一切可通过 DevTools 协议驱动的东西安装期行为自动下载 Chrome及chrome-headless-shell绝不下载任何浏览器默认假设提供大量合理默认值并允许通过配置自定义不预设任何默认值完全通过编程接口驱动依赖关系内部通过puppeteer-core驱动浏览器独立使用不隐式拉取浏览器什么时候该用 puppeteer-core文档明确指出两种典型场景连接远程浏览器——通过puppeteer.connect()连接一个已经运行起来的浏览器实例详见 puppeteer.puppeteer.connect自行管理浏览器——浏览器由你自己的构建、测试或 CI 体系负责安装Puppeteer 只负责「驾驶」这部分工具链可以参考 docs/browsers-api/index.md 中的浏览器安装与启动 API。如果选择自行管理浏览器就必须在puppeteer.launch()时明确告知浏览器在哪传入显式的executablePath浏览器可执行文件的绝对路径或传入channel当浏览器以标准位置安装时用渠道名去定位。两个参数的详细定义可查阅 docs/api/puppeteer.launchoptions.mdlaunch()的完整用法见 docs/api/puppeteer.puppeteernode.launch.md。切换包时别忘改 import从puppeteer切到puppeteer-core后模块名也要随之调整否则仍会触发puppeteer包里的下载逻辑import puppeteer from puppeteer-core;此外官方文档还特别提醒配置文件与环境变量对puppeteer-core一律不生效。换句话说上面介绍的下载控制手段都只属于完整产品包puppeteer。用配置与环境变量精确控制下载行为官方推荐的定制方式是配置文件其次才是环境变量详见 docs/guides/configuration.md。支持哪些配置文件Puppeteer 会沿目录树向上查找以下任一格式查找逻辑实现在 packages/puppeteer/src/getConfiguration.ts基于lilconfigpackage.json.config/puppeteer.config.cjs/.config/puppeteer.config.js.config/puppeteerrc.cjs/.config/puppeteerrc.js/.config/puppeteerrc.json/.config/puppeteerrc.puppeteerrc.cjs/.puppeteerrc.js/.puppeteerrc.json/.puppeteerrcpuppeteer.config.cjs/puppeteer.config.js注意当修改涉及下载选项时必须重跑安装脚本才会生效最简单的做法就是再次执行npx puppeteer browsers install。常用配置项速览Configuration接口的全部字段与默认值定义在 docs/api/puppeteer.configuration.md这里摘录最常被用到的几项配置项说明默认值cacheDirectory浏览器缓存放哪path.join(os.homedir(), .cache, puppeteer)可被PUPPETEER_CACHE_DIR覆盖skipDownload安装时是否跳过全部浏览器下载布尔可被环境变量覆盖logLevel日志级别silent \| error \| warnwarnexecutablePath指定puppeteer.launch()使用的可执行文件路径自动计算可被PUPPETEER_EXECUTABLE_PATH覆盖defaultBrowser默认驱动的浏览器chrome/firefoxchromechrome/chrome-headless-shell/firefox各浏览器专属设置版本、下载源、是否跳过下载Firefox 默认skipDownload: truetemporaryDirectory临时文件目录os.tmpdir()可被PUPPETEER_TMP_DIR覆盖从 packages/puppeteer/src/getConfiguration.ts 的源码可以看到几条容易忽略的合并规则executablePath一旦被显式设置skipDownload会被强制置为 true——既然你自带了浏览器就没必要再下载各浏览器的skipDownload取值优先级依次为PUPPETEER_BROWSER_SKIP_DOWNLOAD/PUPPETEER_SKIP_BROWSER_DOWNLOAD环境变量 → 浏览器级配置 → 全局skipDownload→ 默认值布尔环境变量的解析很宽松0、false、off、空字符串都被视为false其余视为true。环境变量优先级永远最高环境变量在适用时会始终覆盖配置文件。除表格中标注的变量外还需记住三个「仅环境变量可选」的代理设置HTTP_PROXY、HTTPS_PROXY、NO_PROXY它们同时影响浏览器的下载与运行。实际上 packages/puppeteer/src/node/install.ts 里的overrideProxy()会在下载前用 npm 配置npm_config_https_proxy/npm_config_proxy/npm_config_no_proxy去覆盖进程级代理环境变量方便走企业代理或镜像源。示例一同时下载多个浏览器从 v23.0.0 起Puppeteer 支持一次配置、一次命令补全多浏览器无需多次执行命令。在项目根目录新建.puppeteerrc.js/** * type {import(puppeteer).Configuration} */ export default { // 下载 Chrome默认 skipDownload: false。 chrome: { skipDownload: false, }, // 下载 Firefox默认 skipDownload: true。 firefox: { skipDownload: false, }, };然后运行npx puppeteer browsers install示例二修改默认缓存目录v19.0.0 起浏览器默认缓存在~/.cache/puppeteer全局共享。这在「把puppeteer打进构建产物再搬到全新位置」的部署场景下可能引发问题。可以把缓存目录挪到项目自身内部import {join} from path; /** * type {import(puppeteer).Configuration} */ export default { // 修改 Puppeteer 的缓存位置。 cacheDirectory: join(import.meta.dirname, .cache, puppeteer), };修改后需要重新安装puppeteer才会生效。仓库根目录自带的 puppeteer.config.js 就是一个把 Chrome、chrome-headless-shell、Firefox 三者skipDownload全部显式打开的真实示例可作为多浏览器协同开发时的参考模板。常见问题速查报错Could not find Chrome (ver. ...)多半是包管理器拦截了postinstall脚本。优先执行npx puppeteer browsers install手动补下浏览器或在包管理器中把puppeteer的安装脚本加入白名单npm 见上文allowScripts示例。修改下载配置后没生效先确认改动的是puppeteer而非puppeteer-core的配置再重跑npx puppeteer browsers install。下载中断或缓存不完整先用npx puppeteer browsers clear清理缓存再重新执行安装这条建议同样来自 packages/puppeteer/src/node/install.ts 的失败提示逻辑。想完全不让安装期下载设置环境变量PUPPETEER_SKIP_DOWNLOAD1等价于配置skipDownload: true并把executablePath指到你自己的浏览器上。小结一句话总结安装策略默认装puppeteer让 postinstall 阶段自动把兼容版本的 Chrome for Testing 与chrome-headless-shell落到~/.cache/puppeteer只有当你要连接远程浏览器或自行管理浏览器时才改用puppeteer-core并记得用executablePath或channel明确告诉它浏览器在哪里。若被包管理器的脚本拦截策略卡住npx puppeteer browsers install永远是你最可靠的手动补装手段。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Puppeteer 安装完全指南：自动下载机制、puppeteer 与 puppeteer-core 的选型及常见坑位排查
Puppeteer 安装完全指南自动下载机制、puppeteer 与 puppeteer-core 的选型及常见坑位排查【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本文依据 Puppeteer 官方文档 docs/guides/installation.md 展开围绕「如何把 Puppeteer 装进你的项目」这一主题覆盖一条命令快速安装、安装期自动下载 Chrome 的底层机制、现代包管理器拦截安装脚本时的处理方案以及puppeteer与puppeteer-core两个发行包的本质区别与选择依据。读完你将能独立完成安装、按需切换两种包、用配置文件和环境变量精确控制浏览器下载行为并解决诸如Could not find Chrome (ver. ...)之类的经典报错。快速开始一条命令完成安装Puppeteer 是面向 Chrome 与 Firefox 的 JavaScript 自动化 API。在项目中使用它只需要一条命令npm i puppeteer这条命令做的事情远不止「拉取 npm 依赖」这么简单——安装结束后它还会在postinstall阶段触发一次浏览器下载详见下文「安装时到底发生了什么」。因此绝大多数场景下你不需要单独安装浏览器装完即可直接puppeteer.launch()上手。需要注意的是本文讨论的是完整产品包puppeteer的安装路径。仓库中两个发行包的元数据分别位于 packages/puppeteer/package.json 与 packages/puppeteer-core/package.json后者是前者在编译期的直接依赖之一当前版本为puppeteer-core: 25.8.0。安装时到底发生了什么浏览器自动下载机制postinstall 钩子与下载入口在 packages/puppeteer/package.json 的scripts中可以看到一行关键配置postinstall: node install.mjs也就是说每次执行npm i puppeteer含后续的重新安装npm 都会自动运行 packages/puppeteer/install.mjs。该脚本通过动态import(puppeteer/internal/node/install.js)拿到内部安装器并调用其导出的downloadBrowsers()如果 Puppeteer 本体尚未构建比如你直接从源码仓库运行而未先 build它会打印提示并安全退出不会让安装流程崩溃。真正的下载逻辑位于 packages/puppeteer/src/node/install.ts先调用getConfiguration()读取配置文件与环境变量见下文「用配置与环境变量精确控制下载」若配置了skipDownload直接跳过并打印**INFO** Skipping downloading browsers as instructed.否则用detectBrowserPlatform()探测当前平台把浏览器安装到默认缓存目录Chrome、chrome-headless-shell、Firefox 三个下载任务通过Promise.allSettled并发执行全部下载并解压完成后统一打印成功信息避免成功日志插进进度条中间只要有一个任务失败就会抛出提示建议用npx puppeteer browsers install重试或用npx puppeteer browsers clear清理未完成的缓存后重试。会下载什么Chrome for Testing chrome-headless-shell根据 docs/guides/installation.md 的说明安装puppeteer时默认会自动下载一个较新版本的 Chrome for TestingChrome 官方专门为自动化测试发布的构建不与你的日常 Chrome 冲突体积约为 macOS 170MB、Linux 282MB、Windows 280MB一个chrome-headless-shell二进制自 Puppeteer v21.6.0 起引入它是独立于完整 Chrome 的专用 headless 运行载体与 Puppeteer 的版本是保证兼容的。从 packages/puppeteer/src/node/install.ts 的实现可以进一步确认每个浏览器的目标版本优先级是「配置里的version→ 当前发行版内置的PUPPETEER_REVISIONS[browser]→latest」随后通过resolveBuildId()解析出具体的构建号再调用puppeteer/browsers的install()完成下载与解压puppeteer/browsers同样是puppeteer的直接依赖。下载到哪里默认缓存目录浏览器默认被下载到$HOME/.cache/puppeteer该默认自 Puppeteer v19.0.0 起生效后续所有项目共用这一全局缓存避免重复下载。提示如果浏览器因某些原因未随安装下载也可以用 CLI 手工补装。详见 docs/api/puppeteer.configuration.md 对Configuration接口的完整定义以及 docs/guides/configuration.md 的配置指南。自动下载可能被包管理器拦截现象与解决方案:::caution自动下载可能被拦截许多现代包管理器默认禁止依赖执行安装脚本install scripts包括采用了新版 npm RFC 行为的 npm、pnpm、Yarn Berry、Bun、Deno。如果你的包管理器被配置为拦截这些脚本那么安装puppeteer时自动下载就会被静默跳过运行时抛错Could not find Chrome (ver. ...).:::这是因为「下载浏览器」这件事恰好跑在postinstall阶段见上文 packages/puppeteer/package.json而这类脚本正是各家包管理器默认收紧的对象。文档给出两种解决办法方案一安装后手动补装浏览器npx puppeteer browsers install该命令会读取与postinstall完全一致的配置来源把未下载的浏览器补下到位。它本质上就是在手动重放安装期的下载流程因此也是「修改下载相关配置后让其生效」的官方推荐方式见 docs/guides/configuration.md。方案二对 Puppeteer 重新开启 postinstall 脚本以 npm 为例在package.json中加入{ allowScripts: { puppeteer: true } }即可让 npm 在执行安装时允许puppeteer的安装脚本从而恢复自动下载。pnpm、Yarn Berry 等包管理器也有各自等效的「白名单」配置项。puppeteer vs puppeteer-core装哪个、怎么选自 v1.7.0 起官方每个版本都会同时发布两个 npm 包文档反复强调要区分清楚它们的定位——这不是同一份代码的换皮而是「产品」与「库」的本质差异。维度puppeteerpuppeteer-core定位产品product面向开箱即用的浏览器自动化库library面向一切可通过 DevTools 协议驱动的东西安装期行为自动下载 Chrome及chrome-headless-shell绝不下载任何浏览器默认假设提供大量合理默认值并允许通过配置自定义不预设任何默认值完全通过编程接口驱动依赖关系内部通过puppeteer-core驱动浏览器独立使用不隐式拉取浏览器什么时候该用 puppeteer-core文档明确指出两种典型场景连接远程浏览器——通过puppeteer.connect()连接一个已经运行起来的浏览器实例详见 puppeteer.puppeteer.connect自行管理浏览器——浏览器由你自己的构建、测试或 CI 体系负责安装Puppeteer 只负责「驾驶」这部分工具链可以参考 docs/browsers-api/index.md 中的浏览器安装与启动 API。如果选择自行管理浏览器就必须在puppeteer.launch()时明确告知浏览器在哪传入显式的executablePath浏览器可执行文件的绝对路径或传入channel当浏览器以标准位置安装时用渠道名去定位。两个参数的详细定义可查阅 docs/api/puppeteer.launchoptions.mdlaunch()的完整用法见 docs/api/puppeteer.puppeteernode.launch.md。切换包时别忘改 import从puppeteer切到puppeteer-core后模块名也要随之调整否则仍会触发puppeteer包里的下载逻辑import puppeteer from puppeteer-core;此外官方文档还特别提醒配置文件与环境变量对puppeteer-core一律不生效。换句话说上面介绍的下载控制手段都只属于完整产品包puppeteer。用配置与环境变量精确控制下载行为官方推荐的定制方式是配置文件其次才是环境变量详见 docs/guides/configuration.md。支持哪些配置文件Puppeteer 会沿目录树向上查找以下任一格式查找逻辑实现在 packages/puppeteer/src/getConfiguration.ts基于lilconfigpackage.json.config/puppeteer.config.cjs/.config/puppeteer.config.js.config/puppeteerrc.cjs/.config/puppeteerrc.js/.config/puppeteerrc.json/.config/puppeteerrc.puppeteerrc.cjs/.puppeteerrc.js/.puppeteerrc.json/.puppeteerrcpuppeteer.config.cjs/puppeteer.config.js注意当修改涉及下载选项时必须重跑安装脚本才会生效最简单的做法就是再次执行npx puppeteer browsers install。常用配置项速览Configuration接口的全部字段与默认值定义在 docs/api/puppeteer.configuration.md这里摘录最常被用到的几项配置项说明默认值cacheDirectory浏览器缓存放哪path.join(os.homedir(), .cache, puppeteer)可被PUPPETEER_CACHE_DIR覆盖skipDownload安装时是否跳过全部浏览器下载布尔可被环境变量覆盖logLevel日志级别silent \| error \| warnwarnexecutablePath指定puppeteer.launch()使用的可执行文件路径自动计算可被PUPPETEER_EXECUTABLE_PATH覆盖defaultBrowser默认驱动的浏览器chrome/firefoxchromechrome/chrome-headless-shell/firefox各浏览器专属设置版本、下载源、是否跳过下载Firefox 默认skipDownload: truetemporaryDirectory临时文件目录os.tmpdir()可被PUPPETEER_TMP_DIR覆盖从 packages/puppeteer/src/getConfiguration.ts 的源码可以看到几条容易忽略的合并规则executablePath一旦被显式设置skipDownload会被强制置为 true——既然你自带了浏览器就没必要再下载各浏览器的skipDownload取值优先级依次为PUPPETEER_BROWSER_SKIP_DOWNLOAD/PUPPETEER_SKIP_BROWSER_DOWNLOAD环境变量 → 浏览器级配置 → 全局skipDownload→ 默认值布尔环境变量的解析很宽松0、false、off、空字符串都被视为false其余视为true。环境变量优先级永远最高环境变量在适用时会始终覆盖配置文件。除表格中标注的变量外还需记住三个「仅环境变量可选」的代理设置HTTP_PROXY、HTTPS_PROXY、NO_PROXY它们同时影响浏览器的下载与运行。实际上 packages/puppeteer/src/node/install.ts 里的overrideProxy()会在下载前用 npm 配置npm_config_https_proxy/npm_config_proxy/npm_config_no_proxy去覆盖进程级代理环境变量方便走企业代理或镜像源。示例一同时下载多个浏览器从 v23.0.0 起Puppeteer 支持一次配置、一次命令补全多浏览器无需多次执行命令。在项目根目录新建.puppeteerrc.js/** * type {import(puppeteer).Configuration} */ export default { // 下载 Chrome默认 skipDownload: false。 chrome: { skipDownload: false, }, // 下载 Firefox默认 skipDownload: true。 firefox: { skipDownload: false, }, };然后运行npx puppeteer browsers install示例二修改默认缓存目录v19.0.0 起浏览器默认缓存在~/.cache/puppeteer全局共享。这在「把puppeteer打进构建产物再搬到全新位置」的部署场景下可能引发问题。可以把缓存目录挪到项目自身内部import {join} from path; /** * type {import(puppeteer).Configuration} */ export default { // 修改 Puppeteer 的缓存位置。 cacheDirectory: join(import.meta.dirname, .cache, puppeteer), };修改后需要重新安装puppeteer才会生效。仓库根目录自带的 puppeteer.config.js 就是一个把 Chrome、chrome-headless-shell、Firefox 三者skipDownload全部显式打开的真实示例可作为多浏览器协同开发时的参考模板。常见问题速查报错Could not find Chrome (ver. ...)多半是包管理器拦截了postinstall脚本。优先执行npx puppeteer browsers install手动补下浏览器或在包管理器中把puppeteer的安装脚本加入白名单npm 见上文allowScripts示例。修改下载配置后没生效先确认改动的是puppeteer而非puppeteer-core的配置再重跑npx puppeteer browsers install。下载中断或缓存不完整先用npx puppeteer browsers clear清理缓存再重新执行安装这条建议同样来自 packages/puppeteer/src/node/install.ts 的失败提示逻辑。想完全不让安装期下载设置环境变量PUPPETEER_SKIP_DOWNLOAD1等价于配置skipDownload: true并把executablePath指到你自己的浏览器上。小结一句话总结安装策略默认装puppeteer让 postinstall 阶段自动把兼容版本的 Chrome for Testing 与chrome-headless-shell落到~/.cache/puppeteer只有当你要连接远程浏览器或自行管理浏览器时才改用puppeteer-core并记得用executablePath或channel明确告诉它浏览器在哪里。若被包管理器的脚本拦截策略卡住npx puppeteer browsers install永远是你最可靠的手动补装手段。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考