Version: 24.38.0

@puppeteer/browsers

从 CLI 或以编程方式管理和启动浏览器/驱动程序。

🌐 Manage and launch browsers/drivers from a CLI or programmatically.

系统要求

🌐 System requirements

兼容的 Node 版本（参见 engines 在 package.json 中）。
对于 Firefox 下载：
- Linux 构建：需要 xz 和 bzip2 工具来解压 .tar.gz 和 .tar.bz2 压缩包。
- MacOS 构建：解压 .dmg 档案需要 hdiutil。

CLI

使用 npx 来运行命令行接口:

🌐 Use npx to run the 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 所需的所有文档。

🌐 Built-in per-command help will provide all documentation you need to use the 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 的版本：

🌐 You can specify the version of the @puppeteer/browsers when using npx:

# Always install and use the latest version from the registry.
npx @puppeteer/browsers@latest --help
# Always use a specifc 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 命令：

🌐 To clear all installed browsers, use the clear command:

npx @puppeteer/browsers clear

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

🌐 To list all installed browsers, use the list command:

npx @puppeteer/browsers list

一些示例可以让你了解命令行接口（CLI）的样子（使用 --help 命令查看更多示例）：

🌐 Some example to give an idea of what the CLI looks like (use the --help command for more examples):

# 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

已知的限制

🌐 Known limitations

仅适用于 Chrome/Chromium 启动系统浏览器。

自定义提供器

🌐 Custom Providers

你可以实现自定义浏览器提供器，从公司镜像、私有仓库或专门的浏览器构建等替代来源进行下载。

🌐 You can implement custom browser providers to download from alternative sources like corporate mirrors, private repositories, or specialized browser builds.

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 一起使用：

🌐 Use with the 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，作为自动回退。

🌐 Multiple providers can be chained - they're tried in order until one succeeds, with a default provider such as Chrome for Testing, as an automatic fallback.

caution

Puppeteer 官方不支持自定义提供器。你需要对二进制兼容性、测试和维护承担全部责任。

API

该程序化 API 允许从你的代码中安装和启动浏览器。请参阅 test 文件夹以获取有关如何使用 install、canInstall、launch、computeExecutablePath、computeSystemExecutablePath 及其他方法的示例。

🌐 The programmatic API allows installing and launching browsers from your code. See the test folder for examples on how to use the install, canInstall, launch, computeExecutablePath, computeSystemExecutablePath and other methods.

类

🌐 Classes

类 🌐 Class	描述 🌐 Description
CLI
DefaultProvider	使用默认来源的默认提供器实现。这是 Puppeteer 使用的标准提供器。 🌐 Default provider implementation that uses default sources. This is the standard provider used by Puppeteer.
InstalledBrowser	附注这个类的构造函数被标记为内部。第三方代码不应直接调用构造函数或创建继承 `InstalledBrowser` 类的子类。 🌐 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `InstalledBrowser` class.
Process
TimeoutError	附注这个类的构造函数被标记为内部。第三方代码不应直接调用构造函数或创建继承 `TimeoutError` 类的子类。 🌐 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `TimeoutError` class.

枚举

🌐 Enumerations

枚举 🌐 Enumeration	描述 🌐 Description
Browser	支持的浏览器。 🌐 Supported browsers.
BrowserPlatform	平台名称用于以与浏览器下载相关的方式标识操作系统平台 x 架构组合。 🌐 Platform names used to identify a OS platform x architecture combination in the way that is relevant for the browser download.
BrowserTag	描述浏览器发布渠道的枚举。 🌐 Enum describing a release channel for a browser. 你可以将此与 resolveBuildId() 结合使用，以根据发布渠道解析构建 ID。 🌐 You can use this in combination with resolveBuildId() to resolve a build ID based on a release channel.
ChromeReleaseChannel

函数

🌐 Functions

函数 🌐 Function	描述 🌐 Description
buildArchiveFilename(browser, platform, buildId, extension)	用于构建标准归档文件名的实用函数。 🌐 Utility function to build a standard archive filename.
canDownload(options)
computeExecutablePath(options)
computeSystemExecutablePath(options)	通过检查已知的安装位置（使用 https://pptr.nodejs.cn/browsers-api/browsers.computesystemexecutablepath），根据发布通道名称返回系统范围内的 Chrome 安装路径。如果在预期路径未找到 Chrome 实例，则会抛出错误。 🌐 Returns a path to a system-wide Chrome installation given a release channel name by checking known installation locations (using https://pptr.nodejs.cn/browsers-api/browsers.computesystemexecutablepath). If Chrome instance is not found at the expected path, an error is thrown.
createProfile(browser, opts)
detectBrowserPlatform()
getDownloadUrl(browser, platform, buildId, baseUrl)	检索用于下载指定浏览器二进制存档的 URL。 🌐 Retrieves a URL for downloading the binary archive of a given browser. 存档与指定的特定平台和版本 ID 绑定。 🌐 The archive is bound to the specific platform and build ID specified.
getInstalledBrowsers(options)	返回有关安装在缓存目录中的浏览器的元数据。 🌐 Returns metadata about browsers installed in the cache directory.
getVersionComparator(browser)	返回给定浏览器的版本比较器，可用于对浏览器版本进行排序。 🌐 Returns a version comparator for the given browser that can be used to sort browser versions.
install(options)	根据 InstallOptions 下载并解压浏览器归档文件。 🌐 Downloads and unpacks the browser archive according to the InstallOptions.
install(options)	根据 InstallOptions 下载浏览器存档而不进行解压。 🌐 Downloads the browser archive according to the InstallOptions without unpacking.
launch(opts)	根据 LaunchOptions 启动一个浏览器进程。 🌐 Launches a browser process according to LaunchOptions.
makeProgressCallback(browser, buildId)
resolveBuildId(browser, platform, tag)
resolveDefaultUserDataDir(browser, platform, channel)	返回给定渠道的预期默认用户数据目录。它不会检查该目录是否实际存在。 🌐 Returns the expected default user data dir for the given channel. It does not check if the dir actually exists.
uninstall(options)

接口

🌐 Interfaces

界面 🌐 Interface	描述 🌐 Description
BrowserProvider	自定义浏览器提供器实现的接口。允许用户为浏览器实现替代的下载来源。 🌐 Interface for custom browser provider implementations. Allows users to implement alternative download sources for browsers. ⚠️ 重要：Puppeteer 官方不支持自定义提供器。通过实现此接口，你将承担以下全部责任： 🌐 By implementing this interface, you accept full responsibility for: 确保下载的二进制文件与 Puppeteer 的期望兼容 - 测试浏览器启动和其他功能是否与你的二进制文件一起工作 - 当 Puppeteer 或你的下载源更改时保持兼容性 - 如果混合来源，在各平台之间保持版本一致性 Puppeteer 仅测试并保证 Chrome for Testing 二进制文件。 🌐 Puppeteer only tests and guarantees Chrome for Testing binaries.
DownloadOptions	传递给提供者的选项。 🌐 Options passed to a provider.
GetInstalledBrowsersOptions
InstallOptions
LaunchOptions
Metadata
Options
ProfileOptions
SystemOptions
UninstallOptions

变量

🌐 Variables

多变的 🌐 Variable	描述 🌐 Description
CDP_WEBSOCKET_ENDPOINT_REGEX
WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX

多变的

🌐 Variable

描述

🌐 Description

CDP_WEBSOCKET_ENDPOINT_REGEX

WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX

系统要求​

CLI​

已知的限制​

自定义提供器​

API​

类​

枚举​

函数​

接口​

变量​

系统要求

CLI

已知的限制

自定义提供器

API

类

枚举

函数

接口

变量