Puppeteer `@puppeteer/browsers` 之 buildArchiveFilename()：浏览器压缩包标准文件名的构建原理与使用指南

buildArchiveFilename() 是 Puppeteer 生态中 @puppeteer/browsers 包对外导出的一个轻量工具函数，其职责是用统一的约定为某款浏览器、某个平台与某个构建版本生成"标准的压缩包文件名"（standard archive filename）。本文以 docs/browsers-api/browsers.buildarchivefilename.md 为基础，结合仓库中 packages/browsers 的源码，讲解该函数的签名、参数语义、返回值规则、源码实现与导出链路，并通过可运行示例与真实浏览器发行文件的命名对照，帮助你正确理解它在浏览器下载、本地缓存与自定义镜像场景中的定位与用法。

函数定位：它属于哪个包，解决什么问题

buildArchiveFilename() 定义在 @puppeteer/browsers（即本仓库 packages/browsers）中。该包负责"通过 CLI 或以编程方式管理和启动浏览器/驱动"，核心能力包括下载安装 Chrome for Testing、Chromium、Firefox、ChromeDriver 与 chrome-headless-shell，读取安装缓存、解析构建版本、启动浏览器进程等（参见 docs/browsers-api/index.md）。

在这样一个"多浏览器 × 多平台 × 多构建版本"的下载体系中，压缩包文件名是一个反复出现的实体：下载后它要写入缓存目录，镜像站点需要按既定规则存放文件，测试与调试时需要按名称校验产物。buildArchiveFilename() 正是把"这种文件应当叫什么"沉淀成一个可复用的标准函数，保证所有调用方产出的文件名遵循完全一致的约定，避免手写字符串拼接导致的拼写不一致。

从当前源码结构看，该函数在 packages/browsers/src/provider.ts 中定义、并在 packages/browsers/src/main.ts 中被统一 export，供包的外部使用者以 import {buildArchiveFilename} from '@puppeteer/browsers' 的方式调用，是面向下载镜像、缓存工具、脚本等消费方的公共 API。

函数签名与参数语义

原文档给出的完整声明如下：

export declare function buildArchiveFilename(
  browser: Browser,
  platform: BrowserPlatform,
  buildId: string,
  extension?: string,
): string;

参数详解

参数	类型	是否必选	说明
browser	Browser	是	目标浏览器枚举值，决定文件名中的浏览器标识段
platform	BrowserPlatform	是	目标操作系统 × 架构组合，决定文件名中的平台标识段
buildId	string	是	构建版本标识（如 120.0.6099.109），可以是精确版本号，也可以是待解析的别名
extension	string	否	压缩包扩展名，默认值为 zip；省略时自动补 .zip

其中 Browser 与 BrowserPlatform 均来自 packages/browsers/src/browser-data/types.ts，其取值如下：

• Browser（受支持的浏览器）：chrome、chrome-headless-shell、chromium、firefox、chromedriver。
• BrowserPlatform（与浏览器下载相关的 OS 平台 × 架构组合）：linux、linux_arm、mac、mac_arm、win32、win64。

需要注意的是，文档中 extension 参数的描述原文标注为"(Optional)"（可选），而实际源码中该参数带有默认值 'zip'（见下文实现），因此无论是显式传 'zip'、显式传其他扩展名（如 'tar.xz'）还是不传，函数都能返回一个完整合法的文件名。

返回值

返回类型为 string——由参数拼装而成的、带扩展名的标准压缩包文件名。文档的 Returns 段仅标注了 string 类型，其具体拼接规则在源码实现中给出（下一节详述）。

源码实现：一行模板字符串背后的规则

buildArchiveFilename() 的完整实现位于 packages/browsers/src/provider.ts：

export function buildArchiveFilename(
  browser: Browser,
  platform: BrowserPlatform,
  buildId: string,
  extension = 'zip',
): string {
  return `${browser}-${platform}-${buildId}.${extension}`;
}

从源码可以提炼出三条精确规则：

1. 命名模板：最终文件名 = `${browser}-${platform}-${buildId}.${extension}`，即以连字符 - 连接的"浏览器—平台—构建ID"三段 + 一个以 . 分隔的扩展名。
2. 段内容直接取自枚举的字符串值：由于 Browser 与 BrowserPlatform 枚举本身即字符串枚举（例如 Browser.CHROME === 'chrome'、BrowserPlatform.LINUX === 'linux'），模板字符串中直接内插即可得到可读的小写标识，无需再做映射。
3. 扩展名默认值：形参 extension = 'zip' 属于 ES 默认参数语法，调用方不传第四个参数时自动获得 .zip。

由于它只是一个纯字符串拼装函数，不存在网络、文件系统等副作用，因此非常适合在需要"确定性地预测某个版本压缩包文件名"的场景使用。

同时该函数被标记为 @public，并在包入口 packages/browsers/src/main.ts 中被与其他下载相关符号一同转发导出：

export {
  type BrowserProvider,
  buildArchiveFilename,
  type DownloadOptions,
} from './provider.js';

也就是说，函数级别的公共 API 入口是 provider.ts（与 BrowserProvider 接口、DownloadOptions 类型同源），而面向使用者的总入口是 main.ts。

返回值的真实形态：可运行示例

为了直观理解拼接规则，下面是若干个可以直接运行的调用及其返回值（结果均为纯字符串推导，可在任意 Node 环境中验证）：

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

// Linux x64 平台下载 Chrome for Testing 120 版本的"标准文件名"
const name = buildArchiveFilename(
  Browser.CHROME,
  BrowserPlatform.LINUX,
  '120.0.6099.109',
);
// => 'chrome-linux-120.0.6099.109.zip'

调用	返回值
buildArchiveFilename(Browser.CHROME, BrowserPlatform.LINUX, '120.0.6099.109')	chrome-linux-120.0.6099.109.zip
buildArchiveFilename(Browser.CHROMEHEADLESSSHELL, BrowserPlatform.WIN64, '120.0.6099.109')	chrome-headless-shell-win64-120.0.6099.109.zip
buildArchiveFilename(Browser.FIREFOX, BrowserPlatform.MAC_ARM, '129.0')	firefox-mac_arm-129.0.zip
buildArchiveFilename(Browser.CHROMEDRIVER, BrowserPlatform.WIN32, '116.0.5793.0')	chromedriver-win32-116.0.5793.0.zip
buildArchiveFilename(Browser.CHROMIUM, BrowserPlatform.LINUX_ARM, '1234', 'tar.xz')	chromium-linux_arm-1234.tar.xz

注意上表最后一行：当需要适配 Firefox 的 .tar.xz/.tar.bz2 这类非 zip 打包格式时，显式传入第四个参数即可覆盖默认扩展名，这与官方发行物实际使用多种压缩格式的事实是吻合的。

与官方下载源真实文件名的对照：理解"标准名"的边界

在 @puppeteer/browsers 内部，各浏览器的默认下载源并不直接调用 buildArchiveFilename()，而是由各自的 URL 解析模块拼出真实的发行文件名，例如 packages/browsers/src/browser-data/chrome.ts 使用 chrome-${folder(platform)}.zip（如 chrome-linux64.zip、chrome-mac-arm64.zip）；packages/browsers/src/browser-data/firefox.ts 则使用 firefox-${buildId}.en-US.linux-x86_64.tar.xz 一类带语言与架构后缀的命名。这些真实文件名由上游发布方决定，与 buildArchiveFilename() 生成的"标准名"并不要求逐字一致。

由此可以准确归纳该函数的定位边界：

• 它不改变任何下载 URL：URL 的生成仍由 provider 的 getDownloadUrl() 负责（见 docs/browsers-api/browsers.browserprovider.getdownloadurl.md 与 docs/browsers-api/browsers.getdownloadurl.md）；
• 它只负责"本地如何命名归档文件"这一层约定：例如搭建企业内网镜像时，可以先把官方发行物下载到自有存储，再统一命名为标准名以便检索与去重；
• 需要精确"猜测"官方 URL 中文件名时，应直接参考上述 browser-data 下各模块的 resolveDownloadPath/resolveDownloadUrl 实现（如 Chromium 快照路径结构在 packages/browsers/src/browser-data/chromium.ts）。

典型应用场景：镜像归档与本地缓存

场景一：自定义下载源的标准命名

BrowserProvider 接口允许用户为 @puppeteer/browsers 接入企业镜像、私有仓库等替代下载源（详见 docs/browsers-api/index.md 中 "Custom Providers" 一节与 docs/browsers-api/browsers.browserprovider.md）。这类 provider 需要自己返回 getDownloadUrl()，而镜像侧的文件往往可以先用 buildArchiveFilename() 生成统一名称后再分发。由于文件名中已编码了浏览器、平台与构建 ID，同名即同版本同平台，天然便于缓存去重。

场景二：结合 install API 使用

install() 是包的下载安装入口（见 docs/browsers-api/browsers.install.md）。一个把"下载并重命名为标准名落盘"组合起来的工作流大致如下：

import {
  Browser,
  BrowserPlatform,
  buildArchiveFilename,
  resolveBuildId,
} from '@puppeteer/browsers';

async function planArchive() {
  const buildId =
    (await resolveBuildId(
      Browser.CHROME,
      BrowserPlatform.LINUX,
      'stable',
    )) ?? '';
  return buildArchiveFilename(Browser.CHROME, BrowserPlatform.LINUX, buildId);
}

planArchive().then(name => {
  console.log('expected archive:', name);
  // 例如: chrome-linux-130.0.6723.x.zip
});

resolveBuildId() 可把 stable/里程碑号等"标签"解析成精确版本号（见 docs/browsers-api/browsers.resolvebuildid.md），解析结果正好可作为 buildArchiveFilename() 的 buildId 入参，从而在真正下载之前就预知归档文件名。

场景三：跨平台产物自检

当脚本需要同时为 Linux/Mac/Windows 准备多份浏览器产物时，可以先通过 detectBrowserPlatform() 探测当前平台，再结合 buildArchiveFilename() 命名文件，保证产物名与运行环境一致，避免在 win32/win64、mac/mac_arm 这类细粒度平台上拼错文件名。

相关 API 与延伸阅读

• 枚举类型：Browser 与 BrowserPlatform 的完整取值见 docs/browsers-api/browsers.browser.md 与 docs/browsers-api/browsers.browserplatform.md。
• 下载安装：install()（docs/browsers-api/browsers.install.md）、canDownload()（docs/browsers-api/browsers.candownload.md）、uninstall()（docs/browsers-api/browsers.uninstall.md）。
• URL 解析：getDownloadUrl()（docs/browsers-api/browsers.getdownloadurl.md）与 BrowserProvider.getDownloadUrl()（docs/browsers-api/browsers.browserprovider.getdownloadurl.md）。
• 平台与版本：detectBrowserPlatform()（docs/browsers-api/browsers.detectbrowserplatform.md）、resolveBuildId()（docs/browsers-api/browsers.resolvebuildid.md）。
• 包级入口：buildArchiveFilename 在 packages/browsers/src/main.ts 的函数导出清单中亦可见，说明它是面向 @puppeteer/browsers 使用者的公共 API 之一。

小结

buildArchiveFilename() 虽小，却是 @puppeteer/browsers 下载体系命名约定的"最小公因数"：它用 浏览器-平台-构建ID.扩展名 这一模板把多浏览器、多平台、多版本的归档命名统一起来，源码实现仅寥寥数行却规则明确、无副作用、易于测试。理解它，有助于你在自定义镜像、本地缓存与产物自检等场景中，用与官方一致的方式组织浏览器压缩包，避免手写字符串造成的拼写漂移。若需进一步从上层掌握该包的能力，建议从 docs/browsers-api/index.md 的整体 API 索引入手。