企业官网建设流程全解析

Puppeteer Configuration 接口完全指南：用配置文件和环境变量掌控浏览器安装与运行行为

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

Puppeteer 官方将"安装与运行时行为"的全部可调项收敛到Configuration接口中，开发者可以通过配置文件（推荐）或环境变量统一声明浏览器缓存目录、默认浏览器、可执行文件路径、下载开关与日志级别。本文以 Puppeteer 仓库中的docs/api/puppeteer.configuration.md（即Configuration接口的 API 参考）为骨架，结合 Configuration.ts 类型定义、getConfiguration.ts 解析实现与 安装集成测试，完整讲清每一个属性的含义、默认值、可覆盖它的环境变量以及最终生效顺序，帮你做到在 CI、离线构建、多浏览器混跑等场景下"一套配置走天下"。

一、Configuration是什么：安装期与运行期的总开关

Configuration是一个 TypeScriptinterface，官方定位一句话即可概括：

Defines options to configure Puppeteer's behavior during installation and runtime.

也就是它同时管辖两个阶段：

• 安装阶段（installation）：决定puppeteer的 postinstall 是否下载浏览器、下载到哪个目录、下载什么版本、从哪个镜像地址下载；
• 运行阶段（runtime）：决定puppeteer.launch()默认使用哪个浏览器、去哪个路径找可执行文件、日志打到什么级别。

接口签名在 Configuration.ts 中定义：

export interface Configuration { cacheDirectory?: string; executablePath?: string; defaultBrowser?: SupportedBrowser; temporaryDirectory?: string; skipDownload?: boolean; logLevel?: 'silent' | 'error' | 'warn'; experiments?: ExperimentsConfiguration; chrome?: ChromeSettings; ['chrome-headless-shell']?: ChromeHeadlessShellSettings; firefox?: FirefoxSettings; }

使用前提有两个，务必先分清：

1. Configuration属于完整版puppeteer包。官方指南明确指出，配置文件与环境变量都会被puppeteer-core忽略（参见 configuration 指南），因为puppeteer-core不负责下载浏览器，所有浏览器下载能力都封装在puppeteer中。
2. 部分选项只能走环境变量（例如HTTP_PROXY/HTTPS_PROXY/NO_PROXY），无法写进配置文件。

二、顶层属性全表：默认值、类型、可覆盖环境变量

原文档用表格罗列了全部 9 个顶层属性，下表将其完整继承并补齐"来源源码"一列，方便逐一核对：

需要特别强调的是优先级关系：环境变量永远覆盖配置文件。解析器在 getConfiguration.ts 中统一使用process.env['XXX'] ?? configuration.xxx ?? 默认值的三段式合并，这正是阅读该接口全部字段的钥匙。

2.1cacheDirectory：把浏览器缓存搬到项目内或 CI 缓存目录

自 v19.0.0 起浏览器默认全局缓存在~/.cache/puppeteer，方便多项目共享。但它也会带来一个著名问题：当puppeteer在构建步骤中被打包并迁移到新机器后，全局缓存指向失效。官方指南（configuration.md）给出的解法是把缓存目录收敛到项目内：

import {join} from 'path'; /** * @type {import("puppeteer").Configuration} */ export default { // 把缓存目录改到项目自己的 .cache/puppeteer cacheDirectory: join(import.meta.dirname, '.cache', 'puppeteer'), };

仓库内 puppeteer-configuration.test.ts 的 CJS/TS 用例正是用PUPPETEER_CACHE_DIR指向沙箱.cache/puppeteer，并断言下载完成后该目录下同时出现chrome与chrome-headless-shell两个子目录，验证了缓存目录属性直接影响浏览器落盘位置。

2.2defaultBrowser：默认就是 Chrome，可切 Firefox

SupportedBrowser在源码 SupportedBrowser.ts 中仅包含chrome与firefox两个取值。解析时若传入无法识别的值，会直接抛错Unsupported browser ${browser}（见 getConfiguration.ts）：

switch (product) { case 'chrome': case 'firefox': return true; default: return false; }

设置PUPPETEER_BROWSER=firefox或配置文件中的defaultBrowser: 'firefox'后，puppeteer.launch()即默认启动 Firefox。跨浏览器支持的更多上下文可参考 docs/guides/browser-management.md 与 docs/supported-browsers.md。

2.3executablePath：指向系统自带浏览器，并隐式关闭下载

当你不希望 Puppeteer 自己下载浏览器，而想直接用系统 Chrome/Chromium/Firefox 时设置它。它会在puppeteer.launch()中被当作默认可执行路径。最值得注意的隐式行为在 getConfiguration.ts：

configuration.executablePath = process.env['PUPPETEER_EXECUTABLE_PATH'] ?? configuration.executablePath; // 只要设置了 executablePath，就默认不再下载浏览器 if (configuration.executablePath) { configuration.skipDownload = true; }

即一旦提供了可执行文件路径，Puppeteer 自动视为"我已自带浏览器"，无需再执行下载。运行期直接调用也等效：

const browser = await puppeteer.launch({executablePath: '/path/to/Chrome'});

2.4logLevel：silent / error / warn 三级日志

源码 getConfiguration.ts 对取值做了归一化：能识别'silent'与'error'，其余一律回落到默认的'warn'：

function getLogLevel(logLevel: unknown): 'silent' | 'error' | 'warn' { switch (logLevel) { case 'silent': return 'silent'; case 'error': return 'error'; default: return 'warn'; } }

2.5experiments：当前为保留的空结构

ExperimentsConfiguration当前定义为Record<string, never>（见 Configuration.ts），即一个不开放任何字段的类型占位，用于未来承载实验特性。合并配置时解析器也会兜底赋{}，保证该字段永远存在（getConfiguration.ts）。

2.6temporaryDirectory：控制临时文件落点

用于 Puppeteer 创建临时文件的根目录，默认取系统临时目录os.tmpdir()。当系统/tmp空间受限或需要把临时产物固定到特定磁盘时，可通过PUPPETEER_TMP_DIR或该字段调整。

三、浏览器级子配置：chrome/"chrome-headless-shell"/firefox

顶层字段解决"全局"问题，三个浏览器子对象解决"每个浏览器各自的下载策略"。三者形状一致，都包含skipDownload、downloadBaseUrl、version三个字段，接口定义见 Configuration.ts，逐项对比如下：

关键差异是Firefox 默认skipDownload: true，即全新安装 Puppeteer 默认只拉 Chrome 与 chrome-headless-shell，不会下载 Firefox；这一点由 getConfiguration.ts 在合并时传入{skipDownload: true}作为 firefox 的默认配置保证。

每个子对象还允许独立覆盖下载源，规避内网无法访问默认存储桶的问题：

/** @type {import("puppeteer").Configuration} */ module.exports = { chrome: { // 使用内部镜像下载 Chrome downloadBaseUrl: 'https://your-internal-mirror.example.com/chrome-for-testing-public', }, firefox: { // 同时拉取 Firefox（覆盖其默认 skipDownload: true） skipDownload: false, }, };

官方注释对downloadBaseUrl提出了两条硬性约束（见 Configuration.ts）：

• 必须包含协议（https://），甚至可以带上路径前缀；
• 不能以尾部斜杠/结尾。

version的书写格式也因浏览器而异：Chrome 用形如119.0.6045.105的完整版本号，Firefox 用形如stable_129.0的通道/版本组合（源码 Configuration.ts 与 L197 处的@example即为官方示例）。

每个子字段对应的环境变量

浏览器名在拼装环境变量时会被转换为replaceAll('-', '_').toUpperCase()（见 getConfiguration.ts），例如chrome-headless-shell变成CHROME_HEADLESS_SHELL。完整映射：

源码中skipDownload的解析还额外兼容了一套PUPPETEER_SKIP_${BROWSER}_DOWNLOAD旧式命名，并支持''、'0'、'false'、'off'（忽略大小写）四种"假值"写法，其余字符串一律视为真值（getConfiguration.ts）：

function getBooleanEnvVar(name: string): boolean | undefined { const env = process.env[name]; if (env === undefined) return; switch (env.toLowerCase()) { case '': case '0': case 'false': case 'off': return false; default: return true; } }

整体生效优先级（同一字段上高者胜）为：浏览器级专用环境变量 → 全局环境变量 → 配置文件中浏览器子对象的值 → 配置文件中顶层skipDownload→ 内置默认值，这段逻辑完整实现在getBrowserSetting函数中（getConfiguration.ts）。

四、配置文件如何被发现：搜索路径清单

官方把配置文件列为推荐方式。Puppeteer 使用lilconfig以'puppeteer'作为模块名，从当前工作目录向文件树上逐级查找以下文件（getConfiguration.ts）：

• package.json（读取其中的puppeteer键）
• .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、.puppeteerrc
• puppeteer.config.cjs、puppeteer.config.js

命名上.cjs适合 CommonJS 项目，puppeteer.config.ts需要配合 TypeScript 加载器使用（安装测试里就有 TS 场景，见 puppeteer.config.ts）。

修改下载类配置后需重跑安装脚本

下载选项变更（如新增firefox: {skipDownload: false}）不会在下次启动时自动生效，需要重新执行一次安装命令让 postinstall 逻辑按新配置跑一遍（configuration 指南 中明确要求）：

npx puppeteer browsers install

这正是 puppeteer-cli 测试 与配置测试中反复出现的用法。例如配置测试的 CLI 用例先用.puppeteerrc指定browserVersion: 121，再执行npx puppeteer browsers install chrome，随后检查chrome/.metadata中出现aliases['121']，从而证明 CLI 下载严格遵循配置文件中的版本声明（puppeteer-configuration.test.ts）。

五、实战场景：一份可直接落地的配置

场景 A：CI 中同时下载 Chrome + Firefox，并复用项目内缓存

/** * @type {import("puppeteer").Configuration} */ module.exports = { // 缓存到项目目录，方便 CI 将整个 .cache 作为缓存制品 cacheDirectory: require('path').join(__dirname, '.cache', 'puppeteer'), // Chrome 默认就会下载，这里显式声明 chrome: { skipDownload: false, }, // Firefox 默认 skipDownload: true，显式打开以同时下载 firefox: { skipDownload: false, }, };

随后执行：

npx puppeteer browsers install

场景 B：离线/内网环境——跳过下载 + 指定系统浏览器

module.exports = { // 让安装阶段完全跳过浏览器下载 skipDownload: true, // 运行期直接使用机器上已装的 Chrome executablePath: '/usr/bin/google-chrome', };

等价地，也可以不建文件，纯环境变量搞定：

export PUPPETEER_SKIP_DOWNLOAD=true export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

注意executablePath会隐式把skipDownload置为true（见 2.3 节的源码片段），所以即使漏写了skipDownload也不会触发下载。

场景 C：调试期调低日志噪音

/** @type {import("puppeteer").Configuration} */ export default { logLevel: 'error', // 只保留 error 级别，或改为 'silent' 完全静默 };

六、配置在运行时如何被消费

getConfiguration()产出的最终配置会被PuppeteerNode（Node 版入口）等模块读取，用于推断launch()的可执行文件路径与浏览器下载目录等。可执行文件路径的自动推导逻辑（**Auto-computed**默认值所指）与 PuppeteerNode.launch 联动：当未显式传入executablePath时，Puppeteer 依据defaultBrowser、cacheDirectory、各浏览器子配置的version拼出缓存内对应版本的浏览器二进制位置；传入后则直接采用。安装相关命令（如puppeteer browsers install）同样消费同一份合并后的配置，从而保证"配置文件里写什么，安装与运行就按什么来"。入口处的实际装配逻辑可继续阅读 packages/puppeteer/src 目录下PuppeteerNode的启动代码，以及 tools 下的配置消费测试。

七、小结与继续阅读

Configuration接口把 Puppeteer 安装期与运行期的高频可调项收敛成一张清晰的表：8 个全局字段管理缓存、临时目录、浏览器选择、可执行文件与日志；3 个浏览器子对象分别控制 Chrome、chrome-headless-shell、Firefox 的下载开关、下载源与版本；环境变量则拥有最高优先级的"即时覆盖"能力，适合不改文件只改运行环境的场景。

想要继续深挖，可以在仓库内依次阅读：

• 类型定义原文：packages/puppeteer-core/src/common/Configuration.ts
• 合并与优先级实现：packages/puppeteer/src/getConfiguration.ts
• 安装集成测试：test/installation/src/puppeteer-configuration.test.ts 及配套资产 test/installation/assets/puppeteer/configuration
• 配套使用指南：docs/guides/configuration.md
• 相关 API 页：ChromeSettings、ChromeHeadlessShellSettings、FirefoxSettings、SupportedBrowser、ExperimentsConfiguration、PuppeteerNode.launch

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