puppeteer/browsers BrowserProvider.getExecutablePath自定义浏览器 Provider 的可执行文件定位协议【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer导读BrowserProvider.getExecutablePath()是 Puppeteer 浏览器下载/缓存工具链中决定解压后的可执行文件到底在哪一层目录里的关键方法。它告诉安装流程一个下载并解压完毕的浏览器归档其真正的启动程序如chrome、chromedriver、firefox相对于解压根目录位于哪个路径。阅读本文后你将掌握getExecutablePath的签名语义、同步/异步两种实现形态、它在安装与路径解析流程中的调用位置以及如何为自定义下载源编写一份可用的getExecutablePath实现。关联文档BrowserProvider.getExecutablePath()接口总览见 BrowserProvider。方法签名与语义getExecutablePath是BrowserProvider接口定义于 packages/browsers/src/provider.ts的四个成员之一其余为supports、getDownloadUrl、getName。其完整签名如下interface BrowserProvider { getExecutablePath(options: { browser: Browser; buildId: string; platform: BrowserPlatform; }): Promisestring | string; }参数与返回参数类型说明options.browserBrowser目标浏览器标识例如Browser.CHROME、Browser.CHROMEDRIVER、Browser.FIREFOXoptions.buildIdstring浏览器构建号如131.0.6778.109可能为别名解析前的原始值options.platformBrowserPlatform运行平台如BrowserPlatform.LINUX、BrowserPlatform.WIN64、BrowserPlatform.MAC_ARM返回Promisestring | string—— 可执行文件相对于解压根目录的相对路径。方法既可同步返回字符串也可返回 Promise源码注释明确指出两种形态均被接受见 provider.ts这为需要在返回值前做异步平台探测/版本判断的自定义 Provider 保留了余地。在安装流程中的调用位置getExecutablePath并不由使用者直接调用而是被安装器内部驱动。在 packages/browsers/src/install.ts 中install内部的下载解压逻辑拿到归档后会这样做// Get executable path from provider once (used for both cached and new installations) const relativeExecutablePath await provider.getExecutablePath({ browser: options.browser, buildId: options.buildId, platform: options.platform, }); logger?.(DEBUG_PREFIXES.install)?.( Using executable path from provider: ${relativeExecutablePath}, );从源码结构看这一调用发生在unpackArchive解压前、outputPath即缓存中浏览器名/平台-buildId目录确定之后返回值随后被写入安装元数据仅对非默认 Provider并最终拼出InstalledBrowser.executablePath的完整绝对路径。自定义 Provider 的路径持久化同段源码显示若执行安装的 Provider 不是内置的DefaultProvider实例安装器会调用cache.writeExecutablePath(...)把该相对路径写入浏览器的.metadata文件见 install.ts// Write metadata for the installation (only for non-default providers) if (!(provider instanceof DefaultProvider)) { cache.writeExecutablePath( options.browser, options.platform, options.buildId, relativeExecutablePath, ); }对应地在 packages/browsers/src/Cache.ts 的computeExecutablePath中路径解析遵循先读元数据、后走内置规则的顺序如果.metadata里已存有由自定义 Provider 提供的相对路径就直接path.join(installationDir, storedExecutablePath)否则回退到按浏览器类型查表计算的内置相对路径。一个值得注意的校验点同样在 install.ts 中当outputPath已存在时安装器会用existsSync(installedBrowser.executablePath)校验可执行文件是否真实存在缺失时抛出IncompleteInstallationError提示安装目录存在但可执行文件缺失上一次安装可能未完成。这解释了getExecutablePath返回值为何必须与实际归档内部结构严格一致——任何不一致都会在后续启动或二次安装校验中暴露。内置 DefaultProvider 如何实现内置默认 Provider 的getExecutablePath实现非常薄本质是委托给按浏览器分派的路由表见 packages/browsers/src/DefaultProvider.tsgetExecutablePath(options: { browser: Browser; buildId: string; platform: BrowserPlatform; }): string { return executablePathByBrowseroptions.browser; }executablePathByBrowser定义在 packages/browsers/src/browser-data/browser-data.ts为当前支持的 5 种目标分别注册了相对路径函数浏览器枚举路径函数来源文件Browser.CHROMEDRIVERbrowser-data/chromedriver.tsBrowser.CHROMEHEADLESSSHELLbrowser-data/chrome-headless-shell.tsBrowser.CHROMEbrowser-data/chrome.tsBrowser.CHROMIUMbrowser-data/chromium.tsBrowser.FIREFOXbrowser-data/firefox.ts以 Chromedriver 为例其relativeExecutablePathchromedriver.ts按平台分支返回形如chromedriver-folder/chromedriver的路径Windows 平台WIN32/WIN64返回同一路径加.exe后缀macOS 与 Linux 保持一致。类似的平台化差异逻辑同样存在于 Chrome、chrome-headless-shell 与 Firefox 的路径函数中。这说明相对路径不是固定字符串而通常是platform参数的函数因为 Windows 可执行文件带.exe扩展名且归档内部的顶层目录名常随平台与构建号变化。官方文档示例与增强版实现关联文档给出了两个示例第一个针对目录结构固定的 Electron 场景第二个面向需要平台区分的自定义 Provider。此处结合接口注释provider.ts给出可落地的增强版本示例 1固定目录结构Electron 风格// Electron uses simple structure getExecutablePath() { return chromedriver/chromedriver; }适合归档内部结构恒定、不随平台变化的下载源。若目标平台包含 Windows还应补充扩展名判断getExecutablePath(options) { const ext options.platform.includes(win) ? .exe : ; return chromedriver/chromedriver${ext}; }示例 2平台相关的动态路径// Custom provider with platform-specific paths getExecutablePath(options) { return binaries/${options.browser}-${options.platform}; }一个更完整的写法可以借鉴内置实现的平台分支思路async getExecutablePath(options) { const ext options.platform BrowserPlatform.WIN32 || options.platform BrowserPlatform.WIN64 ? .exe : ; const platformFolder { linux: linux64, win32: win64, mac: mac, }[options.platform]; return my-browser-${platformFolder}/mybrowser${ext}; }异步返回的合法用法由于签名允许PromisestringProvider 也可以在返回路径前执行异步探测例如读取解压目录后再确定结构这正是supports/getDownloadUrl也同时接受同步与异步形态的设计意图。编写自定义实现时的注意事项基于源码编写getExecutablePath时应注意以下几点返回的是归档内相对路径而非绝对路径。最终绝对路径由安装器以缓存目录/浏览器名/platform-buildId为基准拼接而成installationDir见 Cache.ts不要在此返回以/或盘符开头的绝对路径。必须与getDownloadUrl指向的归档内部结构一致。接口注释同时强调下载 URL 不被预先校验URL 指向不存在的归档会推迟到下载阶段才失败而结构不一致则会在解压后因找不到可执行文件而失败。目录顶层通常含平台与构建号。内置实现中folder(platform, buildId)参与了路径构成若你的下载源采用了不同的顶层命名请务必在你的 Provider 中如实反映。路径持久化仅对非默认 Provider 生效。instanceof DefaultProvider的实例会跳过元数据写入install.ts因此自定义 Provider 返回的相对路径会被持久化到.metadata并在后续computeExecutablePath中被优先读取。Windows 特殊处理Windows 平台除.exe后缀外Chrome 安装还会在解压后运行setup.exe --configure-browser-in-directory完成沙箱权限配置见 install.ts自定义 Provider 应保证归档内含所需文件结构。自定义 Provider 的完整上下文getExecutablePath只是BrowserProvider的一个环节。要实现一个可用的自定义下载源需同时实现四个方法完整接口见 provider.tsclass MyBrowserProvider implements BrowserProvider { supports(options) { /* 是否处理该 browser/platform 组合 */ } getDownloadUrl(options) { /* 返回下载 URL 或 null */ } getExecutablePath(options) { /* 返回归档内相对路径 */ } getName() { /* 返回 Provider 名称用于日志与报错 */ } }getName()在源码中被特意设计为独立方法而非依赖constructor.name以避免生产构建中类名被压缩混淆后无法定位 Provider接口注释见 provider.ts。整套接口的意义在于当官方默认下载源不可用时你可以基于getDownloadUrl下载getExecutablePath定位supports筛选这三个协议点接入私有镜像、Electron 发布源或企业内网归档。值得强调的是Provider 源码注释明确提示自定义下载源并未得到 Puppeteer 官方测试保证实现者需自行承担二进制兼容性、启动可用性以及 Puppeteer 与下载源各自演进时的维护责任官方仅对 Chrome for Testing 二进制做测试保障provider.ts。相关资源接口 API 文档BrowserProvider、BrowserProvider.getDownloadUrl、BrowserProvider.supports类型定义Browser、BrowserPlatform、DownloadOptions源码接口声明 packages/browsers/src/provider.ts、默认实现 packages/browsers/src/DefaultProvider.ts、调用点 packages/browsers/src/install.ts、路径合成 packages/browsers/src/Cache.ts【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
@puppeteer/browsers BrowserProvider.getExecutablePath：自定义浏览器 Provider 的可执行文件定位协议
puppeteer/browsers BrowserProvider.getExecutablePath自定义浏览器 Provider 的可执行文件定位协议【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer导读BrowserProvider.getExecutablePath()是 Puppeteer 浏览器下载/缓存工具链中决定解压后的可执行文件到底在哪一层目录里的关键方法。它告诉安装流程一个下载并解压完毕的浏览器归档其真正的启动程序如chrome、chromedriver、firefox相对于解压根目录位于哪个路径。阅读本文后你将掌握getExecutablePath的签名语义、同步/异步两种实现形态、它在安装与路径解析流程中的调用位置以及如何为自定义下载源编写一份可用的getExecutablePath实现。关联文档BrowserProvider.getExecutablePath()接口总览见 BrowserProvider。方法签名与语义getExecutablePath是BrowserProvider接口定义于 packages/browsers/src/provider.ts的四个成员之一其余为supports、getDownloadUrl、getName。其完整签名如下interface BrowserProvider { getExecutablePath(options: { browser: Browser; buildId: string; platform: BrowserPlatform; }): Promisestring | string; }参数与返回参数类型说明options.browserBrowser目标浏览器标识例如Browser.CHROME、Browser.CHROMEDRIVER、Browser.FIREFOXoptions.buildIdstring浏览器构建号如131.0.6778.109可能为别名解析前的原始值options.platformBrowserPlatform运行平台如BrowserPlatform.LINUX、BrowserPlatform.WIN64、BrowserPlatform.MAC_ARM返回Promisestring | string—— 可执行文件相对于解压根目录的相对路径。方法既可同步返回字符串也可返回 Promise源码注释明确指出两种形态均被接受见 provider.ts这为需要在返回值前做异步平台探测/版本判断的自定义 Provider 保留了余地。在安装流程中的调用位置getExecutablePath并不由使用者直接调用而是被安装器内部驱动。在 packages/browsers/src/install.ts 中install内部的下载解压逻辑拿到归档后会这样做// Get executable path from provider once (used for both cached and new installations) const relativeExecutablePath await provider.getExecutablePath({ browser: options.browser, buildId: options.buildId, platform: options.platform, }); logger?.(DEBUG_PREFIXES.install)?.( Using executable path from provider: ${relativeExecutablePath}, );从源码结构看这一调用发生在unpackArchive解压前、outputPath即缓存中浏览器名/平台-buildId目录确定之后返回值随后被写入安装元数据仅对非默认 Provider并最终拼出InstalledBrowser.executablePath的完整绝对路径。自定义 Provider 的路径持久化同段源码显示若执行安装的 Provider 不是内置的DefaultProvider实例安装器会调用cache.writeExecutablePath(...)把该相对路径写入浏览器的.metadata文件见 install.ts// Write metadata for the installation (only for non-default providers) if (!(provider instanceof DefaultProvider)) { cache.writeExecutablePath( options.browser, options.platform, options.buildId, relativeExecutablePath, ); }对应地在 packages/browsers/src/Cache.ts 的computeExecutablePath中路径解析遵循先读元数据、后走内置规则的顺序如果.metadata里已存有由自定义 Provider 提供的相对路径就直接path.join(installationDir, storedExecutablePath)否则回退到按浏览器类型查表计算的内置相对路径。一个值得注意的校验点同样在 install.ts 中当outputPath已存在时安装器会用existsSync(installedBrowser.executablePath)校验可执行文件是否真实存在缺失时抛出IncompleteInstallationError提示安装目录存在但可执行文件缺失上一次安装可能未完成。这解释了getExecutablePath返回值为何必须与实际归档内部结构严格一致——任何不一致都会在后续启动或二次安装校验中暴露。内置 DefaultProvider 如何实现内置默认 Provider 的getExecutablePath实现非常薄本质是委托给按浏览器分派的路由表见 packages/browsers/src/DefaultProvider.tsgetExecutablePath(options: { browser: Browser; buildId: string; platform: BrowserPlatform; }): string { return executablePathByBrowseroptions.browser; }executablePathByBrowser定义在 packages/browsers/src/browser-data/browser-data.ts为当前支持的 5 种目标分别注册了相对路径函数浏览器枚举路径函数来源文件Browser.CHROMEDRIVERbrowser-data/chromedriver.tsBrowser.CHROMEHEADLESSSHELLbrowser-data/chrome-headless-shell.tsBrowser.CHROMEbrowser-data/chrome.tsBrowser.CHROMIUMbrowser-data/chromium.tsBrowser.FIREFOXbrowser-data/firefox.ts以 Chromedriver 为例其relativeExecutablePathchromedriver.ts按平台分支返回形如chromedriver-folder/chromedriver的路径Windows 平台WIN32/WIN64返回同一路径加.exe后缀macOS 与 Linux 保持一致。类似的平台化差异逻辑同样存在于 Chrome、chrome-headless-shell 与 Firefox 的路径函数中。这说明相对路径不是固定字符串而通常是platform参数的函数因为 Windows 可执行文件带.exe扩展名且归档内部的顶层目录名常随平台与构建号变化。官方文档示例与增强版实现关联文档给出了两个示例第一个针对目录结构固定的 Electron 场景第二个面向需要平台区分的自定义 Provider。此处结合接口注释provider.ts给出可落地的增强版本示例 1固定目录结构Electron 风格// Electron uses simple structure getExecutablePath() { return chromedriver/chromedriver; }适合归档内部结构恒定、不随平台变化的下载源。若目标平台包含 Windows还应补充扩展名判断getExecutablePath(options) { const ext options.platform.includes(win) ? .exe : ; return chromedriver/chromedriver${ext}; }示例 2平台相关的动态路径// Custom provider with platform-specific paths getExecutablePath(options) { return binaries/${options.browser}-${options.platform}; }一个更完整的写法可以借鉴内置实现的平台分支思路async getExecutablePath(options) { const ext options.platform BrowserPlatform.WIN32 || options.platform BrowserPlatform.WIN64 ? .exe : ; const platformFolder { linux: linux64, win32: win64, mac: mac, }[options.platform]; return my-browser-${platformFolder}/mybrowser${ext}; }异步返回的合法用法由于签名允许PromisestringProvider 也可以在返回路径前执行异步探测例如读取解压目录后再确定结构这正是supports/getDownloadUrl也同时接受同步与异步形态的设计意图。编写自定义实现时的注意事项基于源码编写getExecutablePath时应注意以下几点返回的是归档内相对路径而非绝对路径。最终绝对路径由安装器以缓存目录/浏览器名/platform-buildId为基准拼接而成installationDir见 Cache.ts不要在此返回以/或盘符开头的绝对路径。必须与getDownloadUrl指向的归档内部结构一致。接口注释同时强调下载 URL 不被预先校验URL 指向不存在的归档会推迟到下载阶段才失败而结构不一致则会在解压后因找不到可执行文件而失败。目录顶层通常含平台与构建号。内置实现中folder(platform, buildId)参与了路径构成若你的下载源采用了不同的顶层命名请务必在你的 Provider 中如实反映。路径持久化仅对非默认 Provider 生效。instanceof DefaultProvider的实例会跳过元数据写入install.ts因此自定义 Provider 返回的相对路径会被持久化到.metadata并在后续computeExecutablePath中被优先读取。Windows 特殊处理Windows 平台除.exe后缀外Chrome 安装还会在解压后运行setup.exe --configure-browser-in-directory完成沙箱权限配置见 install.ts自定义 Provider 应保证归档内含所需文件结构。自定义 Provider 的完整上下文getExecutablePath只是BrowserProvider的一个环节。要实现一个可用的自定义下载源需同时实现四个方法完整接口见 provider.tsclass MyBrowserProvider implements BrowserProvider { supports(options) { /* 是否处理该 browser/platform 组合 */ } getDownloadUrl(options) { /* 返回下载 URL 或 null */ } getExecutablePath(options) { /* 返回归档内相对路径 */ } getName() { /* 返回 Provider 名称用于日志与报错 */ } }getName()在源码中被特意设计为独立方法而非依赖constructor.name以避免生产构建中类名被压缩混淆后无法定位 Provider接口注释见 provider.ts。整套接口的意义在于当官方默认下载源不可用时你可以基于getDownloadUrl下载getExecutablePath定位supports筛选这三个协议点接入私有镜像、Electron 发布源或企业内网归档。值得强调的是Provider 源码注释明确提示自定义下载源并未得到 Puppeteer 官方测试保证实现者需自行承担二进制兼容性、启动可用性以及 Puppeteer 与下载源各自演进时的维护责任官方仅对 Chrome for Testing 二进制做测试保障provider.ts。相关资源接口 API 文档BrowserProvider、BrowserProvider.getDownloadUrl、BrowserProvider.supports类型定义Browser、BrowserPlatform、DownloadOptions源码接口声明 packages/browsers/src/provider.ts、默认实现 packages/browsers/src/DefaultProvider.ts、调用点 packages/browsers/src/install.ts、路径合成 packages/browsers/src/Cache.ts【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
