@puppeteer/browsers

通过 CLI 或编程方式管理并启动浏览器/驱动程序。

系统要求

• 兼容的 Node 版本（参见 package.json 中的 engines）。
• 对于 Firefox 下载：
  • Linux 构建：解压 .tar.gz 和 .tar.bz2 归档文件需要 xz 和 bzip2 工具。
  • MacOS 构建：解压 .dmg 归档文件需要 hdiutil。
• 对于 Chrome 下载：
  • 在 Linux/MacOS 上：unzip。
  • 在 Windows 上：tar.exe。

CLI

使用 npx 运行 CLI：

# This will install and run the @puppeteer/browsers package.
# If it is already installed in the current directory, the installed
# version will be used.
npx @puppeteer/browsers --help

内置的逐命令 help 会提供使用 CLI 所需的全部文档。

npx @puppeteer/browsers --help # help for all commands
npx @puppeteer/browsers install --help # help for the install command
npx @puppeteer/browsers launch --help # help for the launch command
npx @puppeteer/browsers clear --help # help for the clear command
npx @puppeteer/browsers list --help # help for the list command

使用 npx 时，你可以指定 @puppeteer/browsers 的版本：

# Always install and use the latest version from the registry.
npx @puppeteer/browsers@latest --help
# Always use a specific version.
npx @puppeteer/browsers@2.4.1 --help
# Always install the latest version and automatically confirm the installation.
npx --yes @puppeteer/browsers@latest --help

要清除所有已安装的浏览器，请使用 clear 命令：

npx @puppeteer/browsers clear

要列出所有已安装的浏览器，请使用 list 命令：

npx @puppeteer/browsers list

以下示例可帮助你了解 CLI 的用法（更多示例请使用 --help 命令）：

# Download the latest available Chrome for Testing binary corresponding to the Stable channel.
npx @puppeteer/browsers install chrome@stable

# Download a specific Chrome for Testing version.
npx @puppeteer/browsers install chrome@116.0.5793.0

# Download the latest Chrome for Testing version for the given milestone.
npx @puppeteer/browsers install chrome@117

# Download the latest available ChromeDriver version corresponding to the Canary channel.
npx @puppeteer/browsers install chromedriver@canary

# Download a specific ChromeDriver version.
npx @puppeteer/browsers install chromedriver@116.0.5793.0

# On Ubuntu/Debian and only for Chrome, install the browser and required system dependencies.
# If the browser version has already been installed, the command
# will still attempt to install system dependencies.
# Requires root privileges.
npx puppeteer browsers install chrome --install-deps

已知限制

1. 只有 Chrome/Chromium 可以启动系统浏览器。

代理

该库和 CLI 遵循 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。要让它们生效，你必须安装 proxy-agent 包：

npm install proxy-agent

调试

要为 @puppeteer/browsers 操作启用详细日志（如下载进度、安装步骤和启动参数），请使用 Node.js 内置的 NODE_DEBUG 环境变量。

env NODE_DEBUG="puppeteer:browsers:*" npx @puppeteer/browsers install chrome@stable

以下调试通道可用：

• puppeteer:browsers:cache：缓存操作。
• puppeteer:browsers:fileUtil：解压及其他文件工具操作。
• puppeteer:browsers:install：下载和安装进度。
• puppeteer:browsers:launcher：浏览器启动参数和进程状态。

自定义提供程序

你可以实现自定义浏览器提供程序，从替代源下载，例如公司镜像、私有仓库或专用的浏览器构建。

import {
  BrowserProvider,
  DownloadOptions,
  Browser,
  BrowserPlatform,
} from '@puppeteer/browsers';

class SimpleMirrorProvider implements BrowserProvider {
  constructor(private mirrorUrl: string) {}

  supports(options: DownloadOptions): boolean {
    return options.browser === Browser.CHROME;
  }

  getDownloadUrl(options: DownloadOptions): URL | null {
    const {buildId, platform} = options;
    const filenameMap = {
      [BrowserPlatform.LINUX]: 'chrome-linux64.zip',
      [BrowserPlatform.MAC]: 'chrome-mac-x64.zip',
      [BrowserPlatform.MAC_ARM]: 'chrome-mac-arm64.zip',
      [BrowserPlatform.WIN32]: 'chrome-win32.zip',
      [BrowserPlatform.WIN64]: 'chrome-win64.zip',
    };
    const filename = filenameMap[platform];
    if (!filename) return null;
    return new URL(`${this.mirrorUrl}/chrome/${buildId}/${filename}`);
  }

  getExecutablePath(options: DownloadOptions): string {
    const {platform} = options;
    if (
      platform === BrowserPlatform.MAC ||
      platform === BrowserPlatform.MAC_ARM
    ) {
      return 'chrome-mac/Chromium.app/Contents/MacOS/Chromium';
    } else if (platform === BrowserPlatform.LINUX) {
      return 'chrome-linux64/chrome';
    } else if (platform.includes('win')) {
      return 'chrome-win64/chrome.exe';
    }
    throw new Error(`Unsupported platform: ${platform}`);
  }
}

与 install API 一起使用：

import {install} from '@puppeteer/browsers';

const customProvider = new SimpleMirrorProvider('https://internal.company.com');

await install({
  browser: Browser.CHROME,
  buildId: '120.0.6099.109',
  platform: BrowserPlatform.LINUX,
  cacheDir: '/tmp/puppeteer-cache',
  providers: [customProvider],
});

多个提供程序可以串联使用——它们会按顺序依次尝试，直到其中一个成功，并以默认提供程序（如 Chrome for Testing）作为自动回退。

API

编程式 API 允许你从代码中安装和启动浏览器。有关如何使用 install、canInstall、launch、computeExecutablePath、computeSystemExecutablePath 等方法，请参阅 test 文件夹中的示例。

类

枚举

函数

接口

变量