Skip to main content
Version: 24.38.0

配置

🌐 Configuration

默认情况下，Puppeteer 会下载并使用特定版本的 Chrome，因此其 API 可以开箱即用。要在不同版本的 Chrome 或 Chromium 上使用 Puppeteer，请在创建 Browser 实例时传入可执行文件的路径：

🌐 By default, Puppeteer downloads and uses a specific version of Chrome so its API is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome or Chromium, pass in the executable's path when creating a Browser instance:

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

你也可以在 Firefox 上使用 Puppeteer。有关更多信息，请参阅跨浏览器支持状态。

🌐 You can also use Puppeteer with Firefox. See status of cross-browser support for more information.

Puppeteer 中的所有默认设置都可以通过两种方式进行自定义：

🌐 All defaults in Puppeteer can be customized in two ways:

  1. 配置文件 (推荐)
  2. 环境变量
caution

请注意，有些选项只能通过环境变量（例如 HTTPS_PROXY）进行自定义。

🌐 Note that some options are only customizable through environment variables (such as HTTPS_PROXY).

caution

Puppeteer 的配置文件和环境变量会被 puppeteer-core 忽略。

🌐 Puppeteer's configuration files and environment variables are ignored by puppeteer-core.

配置文件​

🌐 Configuration files

配置文件是配置 Puppeteer 的推荐选择。 Puppeteer 会在文件树中查找以下任意格式的文件：

🌐 Configuration files are the recommended choice for configuring Puppeteer. Puppeteer will look up the file tree for any of the following formats:

  • .puppeteerrc.cjs,
  • .puppeteerrc.js,
  • .puppeteerrc（YAML/JSON），
  • .puppeteerrc.json,
  • .puppeteerrc.yaml,
  • puppeteer.config.js，和
  • puppeteer.config.cjs

有关可能的选项，请参阅 Configuration 接口。

🌐 See the Configuration interface for possible options.

更改下载选项​

🌐 Changing download options

当配置的更改包括下载选项的更改时，你需要重新运行安装后脚本以使其生效。

🌐 When the changes to the configuration include changes to download option, you will need to re-run postinstall scripts for them to take effect.

这可以通过运行最轻松地完成：

🌐 This can most easily be done with running:

npx puppeteer browsers install

示例​

🌐 Examples

下载多个浏览器​

🌐 Downloading multiple browsers

从 v23.0.0 开始，Puppeteer 允许下载多个浏览器，而无需运行多个命令。

🌐 Starting with v23.0.0, Puppeteer allows downloading multiple browser without the need to run multiple commands.

更新 Puppeteer 配置文件：

🌐 Update the Puppeteer configuration file:

project-directory/.puppeteerrc.cjs
/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  // Download Chrome (default `skipDownload: false`).
  chrome: {
    skipDownload: false,
  },
  // Download Firefox (default `skipDownload: true`).
  firefox: {
    skipDownload: false,
  },
};

运行 CLI 下载新配置：

🌐 Run CLI to download the new configuration:

npx puppeteer browsers install

更改默认缓存目录​

🌐 Changing the default cache directory

从 v19.0.0 开始，Puppeteer 将浏览器存储在 ~/.cache/puppeteer 中，以便在安装之间全局缓存浏览器。这可能会导致问题，如果 puppeteer 在某些构建步骤中被打包并移动到新的位置。以下配置可以解决此问题（重新安装 puppeteer 以生效）：

🌐 Starting in v19.0.0, Puppeteer stores browsers in ~/.cache/puppeteer to globally cache browsers between installation. This can cause problems if puppeteer is packed during some build step and moved to a fresh location. The following configuration can solve this issue (reinstall puppeteer to take effect):

project-directory/.puppeteerrc.cjs
const {join} = require('path');

/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  // Changes the cache location for Puppeteer.
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};
note

请注意，这仅适用于 CommonJS 配置文件，因为需要关于环境信息（在此情况下为 __dirname）。

🌐 Notice this is only possible with CommonJS configuration files as information about the ambient environment is needed (in this case, __dirname).

环境变量​

🌐 Environment variables

除了配置文件之外，Puppeteer 还会查找某些环境变量以自定义行为。在适用的情况下，环境变量总是会覆盖配置文件选项。

🌐 Along with configuration files, Puppeteer looks for certain environment variables for customizing behavior. Environment variables will always override configuration file options when applicable.

以下选项是 仅限环境 选项

🌐 The following options are environment-only options

  • HTTP_PROXY、HTTPS_PROXY、NO_PROXY - 定义用于下载和运行浏览器的 HTTP 代理设置。

所有其他选项可以在Configuration接口的文档中找到。

🌐 All other options can be found in the documentation for the Configuration interface.