Puppeteer `defaultArgs()` 深度解析：Chrome 与 Firefox 默认启动参数是如何组装的

PuppeteerdefaultArgs()深度解析：Chrome 与 Firefox 默认启动参数是如何组装的

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer

本文围绕 Puppeteer API 文档中的 defaultArgs() 函数展开：先完整继承官方 API 的函数签名、参数与返回值定义，再结合仓库中 PuppeteerNode、ChromeLauncher 与 FirefoxLauncher 的源码，逐项拆解 Chrome / Firefox 两套默认启动参数的真实清单、条件分支逻辑（headless、devtools、userDataDir、特性开关等），并说明该函数与launch()中ignoreDefaultArgs的调用关系。读完后，你能够准确预测 Puppeteer 启动浏览器时会传入哪些命令行参数，以及如何安全地过滤或替换其中某一项。

一、API 定义：签名、参数与返回值

按 docs/api/puppeteer.defaultargs.md 的官方定义，defaultArgs的 TypeScript 签名为：

defaultArgs: (options?: PuppeteerCore.LaunchOptions) => Promise<string[]>;

参数	类型	说明
options	PuppeteerCore.LaunchOptions	可选（Optional），传入 LaunchOptions 以影响默认参数的计算方式

返回值：Promise<string[]>—— 一个解析为字符串数组的 Promise，数组中的每一项都是一条完整的浏览器命令行参数（例如--headless=new）。

这个函数在 Node 版入口被导出：puppeteer包在 packages/puppeteer/src/puppeteer.ts 中从PuppeteerNode实例上解构导出connect、defaultArgs、executablePath、launch、trimCache、setFollowSymlinks等顶层 API。因此你在脚本中写puppeteer.defaultArgs()时，调用的是 PuppeteerNode.defaultArgs：

/** * @param options - Set of configurable options to set on the browser. * * @returns The default arguments that the browser will be launched with. */ async defaultArgs(options: LaunchOptions = {}): Promise<string[]> { return this.#getLauncher( options.browser ?? (await this.lastLaunchedBrowser()), options.logger ?? debug, ).defaultArgs(options); }

从源码结构看，它的行为可以概括为两点：

1. 按浏览器路由：以options.browser为准；未指定时回退到lastLaunchedBrowser()（即上次启动的浏览器，或配置/默认的chrome），随后分派到ChromeLauncher.defaultArgs()或FirefoxLauncher.defaultArgs()。两个 Launcher 中的defaultArgs本身是同步方法，外层的async只体现在浏览器路由的解析上。
2. 只计算、不启动：该函数纯粹是“参数预览”，不会创建进程，也不会校验可执行文件是否存在。它返回的正是launch()内部computeLaunchArguments将要拼进进程参数的核心部分。

二、Chrome 默认参数全清单（ChromeLauncher.defaultArgs）

Chrome 的实现位于 ChromeLauncher.ts 第 167–297 行。源码注释直接引用了 Chrome 官方 launcher 工具的 flag 文档，下面把完整逻辑分块还原。

2.1 特性开关的合并：--enable-features与--disable-features

Puppeteer 会先从用户传入的options.args中提取--enable-features=...与--disable-features=...（借助 getFeatures 按逗号拆分、去空白），然后用 removeMatchingFlags 把这些 flag 从用户参数中原地删除，再与内置默认值合并。也就是说用户特性与内置特性是合并而非覆盖。

默认启用（enabled）的特性：

• PdfOopif
• 用户在args中通过--enable-features指定的全部特性

默认禁用（disabled）的特性：

• Translate
• AcceptCHFrame（源码注明因 crbug.com/1348106 而禁用）
• MediaRouter
• OptimizationHints
• WebUIReloadButton
• WebUIOmniboxPopup
• WebUIOmniboxAimPopup
• 以下两项仅在环境变量PUPPETEER_TEST_EXPERIMENTAL_CHROME_FEATURES不等于'true'时加入（即默认被禁用，测试场景可显式放开）：
  • ProcessPerSiteUpToMainFrameThreshold（关联 crbug.com/1492053）
  • IsolateSandboxedIframes（关联上游 issue #10715）
• 用户在args中通过--disable-features指定的全部特性

合并后有一个去重规则：同时出现在启用列表与禁用列表中的特性，以“启用”为准（禁用列表会过滤掉已启用的条目）。最终生成--disable-features=A,B,...与--enable-features=...两条参数（过滤掉空字符串项）。

2.2 固定的基础参数（无条件追加）

以下参数按源码顺序固定出现在返回数组中（headless分支项除外，见 2.3）：

--allow-pre-commit-input --disable-background-networking --disable-background-timer-throttling --disable-backgrounding-occluded-windows --disable-breakpad --disable-client-side-phishing-detection --disable-component-extensions-with-background-pages --disable-crash-reporter // 源码注释：No crash reporting in CfT. --disable-default-apps --disable-dev-shm-usage --disable-hang-monitor --disable-infobars --disable-ipc-flooding-protection --disable-popup-blocking --disable-prompt-on-repost --disable-renderer-backgrounding --disable-search-engine-choice-screen --disable-sync --enable-automation --export-tagged-pdf --force-color-profile=srgb --generate-pdf-document-outline --metrics-recording-only --no-first-run --password-store=basic --use-mock-keychain --disable-features=<合并后的禁用特性> --enable-features=<合并后的启用特性>

这些参数大多服务于“自动化场景”：关闭崩溃上报与后台行为、固定 sRGB 色彩剖面保证截图/PDF 颜色一致、用基础密码存储与 mock keychain 避免依赖系统钥匙串、--enable-automation打开自动化标记等。

2.3 条件分支参数

条件	追加的参数
环境变量PUPPETEER_DANGEROUS_NO_SANDBOX === 'true'且用户args未包含--no-sandbox	--no-sandbox
传入options.userDataDir	--user-data-dir=<path>（绝对路径原样使用；相对路径会用path.resolve解析，且同时按 POSIX / Windows 规则判断绝对性）
devtools: true（此时headless被强制为false，因为源码中headless = !devtools）	--auto-open-devtools-for-tabs
headless: true（默认值）	--headless=new、--hide-scrollbars、--mute-audio
headless: 'shell'	--headless（旧版 shell 模式），同样追加--hide-scrollbars、--mute-audio
enableExtensions不为true	--disable-extensions
用户args中每一项都以-开头（即没有提供初始 URL）	在用户参数前插入about:blank

最后，用户自定义的options.args被整体追加到数组末尾，因此用户参数在命令行中排最后，且其中的特性类 flag 已被前面合并逻辑消化过。

三、Firefox 默认参数（FirefoxLauncher.defaultArgs）

Firefox 侧的实现位于 FirefoxLauncher.ts 第 182–219 行，比 Chrome 精简得多：

switch (os.platform()) { case 'darwin': firefoxArguments.push('--foreground'); break; case 'win32': firefoxArguments.push('--wait-for-browser'); break; }

条件	追加的参数
平台为 macOS（darwin）	--foreground
平台为 Windows（win32）	--wait-for-browser
传入options.userDataDir	--profile <userDataDir>（两个独立数组元素，Firefox 采用空格分隔的参数形式）
headless为真（默认，且非 devtools）	--headless
devtools: true	--devtools
用户args全部以-开头	插入about:blank

最后同样把用户options.args追加到末尾。注意：Firefox 的 profile 真正生效还依赖computeLaunchArguments中 createProfile 写入的偏好文件（getPreferences 会强制fission.webContentIsolationStrategy: 0，源码注释关联了 Mozilla bug 1773393），但 profile 的创建属于launch流程，不属于defaultArgs返回内容。

四、defaultArgs()与launch()的调用关系

理解defaultArgs最有价值的场景是搞清楚ignoreDefaultArgs的三种形态。两个 Launcher 的computeLaunchArguments（ChromeLauncher.ts 第 65–149 行、FirefoxLauncher.ts 第 45–131 行）遵循同一套分支：

if (!ignoreDefaultArgs) { // 全量默认参数 chromeArguments.push(...this.defaultArgs(options)); } else if (Array.isArray(ignoreDefaultArgs)) { // 默认参数中逐项过滤掉列出的参数 chromeArguments.push( ...this.defaultArgs(options).filter(arg => { return !ignoreDefaultArgs.includes(arg); }), ); } else { // ignoreDefaultArgs === true：只使用用户 args chromeArguments.push(...args); }

• ignoreDefaultArgs缺省为false（见 LaunchOptions.ts 第 56–61 行）：完整使用defaultArgs()结果。
• 传数组：按“精确整条字符串”过滤。PuppeteerNode 的文档示例是ignoreDefaultArgs: ['--mute-audio']（PuppeteerNode.ts 第 111–119 行）。注意过滤是整项相等匹配，--mute-audio能匹配，但想按前缀或子串过滤是不行的。
• 传true：完全绕过defaultArgs()，最终参数只剩用户args加上后续补足的调试端口参数。LaunchOptions 的注释也明确提醒“Use this with care - you probably want the default arguments Puppeteer uses”。

在分支之后，launch流程还会继续做两件事（这部分不属于defaultArgs()返回值，但决定了最终命令行）：

1. 若参数中没有任何以--remote-debugging-开头的项，则根据pipe选项追加--remote-debugging-pipe，或追加--remote-debugging-port=<debuggingPort || 0>（0表示随机端口）；
2. 若参数中没有--user-data-dir（Chrome），则在临时目录puppeteer_dev_chrome_profile-下mkdtemp创建一个临时 profile 并追加参数，见 BrowserLauncher.getProfilePath。

因此，puppeteer.defaultArgs()的输出是launch最终参数的“主体子集”，二者差值基本只有调试端点与兜底 profile 相关项——这也解释了为何测试 ChromeLauncher.test.ts 会直接调用launcher.defaultArgs({...})来断言参数拼装结果。

五、验证与回归测试

仓库内置了两处对defaultArgs行为的自动化验证：

1. PuppeteerNode.test.ts 第 87–100 行：构造PuppeteerNode实例后调用await puppeteer.defaultArgs()，断言返回值为Array实例——覆盖了“无参数调用”这一最常见用法，与本文档签名中options?可选的设计一致。
2. ChromeLauncher.test.ts：直接调用launcher.defaultArgs({...})对具体 LaunchOptions 组合下的参数做细粒度断言，是特性合并与条件分支逻辑的回归保障。

如果你想在自己的环境里快速核对行为，最直接的方式就是打印：

import puppeteer from 'puppeteer'; // 无参：等价于 Chrome 默认参数（headless 为 true 时的完整清单） console.log(await puppeteer.defaultArgs()); // 指定 Firefox console.log(await puppeteer.defaultArgs({browser: 'firefox'})); // 预览用户参数合并后的结果（含 --enable-features 合并逻辑） console.log( await puppeteer.defaultArgs({ args: ['--enable-features=NetworkServiceInProcess'], }), );

六、使用建议与注意事项

• 用defaultArgs()做诊断：它不启动浏览器，适合在排查launch()失败时先打印实际将要传入的命令行（例如确认--user-data-dir解析结果、特性开关合并是否符合预期）。
• 过滤参数优先用数组形式：ignoreDefaultArgs: ['--mute-audio']这类做法保留其余默认参数，风险可控；ignoreDefaultArgs: true会让--disable-dev-shm-usage、--no-first-run等保障项全部缺失，容器/CI 环境下容易引入新的不稳定因素。
• --no-sandbox不能通过args之外的官方开关控制：源码只在检测到PUPPETEER_DANGEROUS_NO_SANDBOX === 'true'时才自动追加（ChromeLauncher.ts 第 262–267 行）；当然你也可以直接在launch({args: ['--no-sandbox']})中显式传入，它会作为用户参数追加在最后。
• 过滤是按整条字符串精确匹配：由于特性参数是逗号拼接的长字符串（如--disable-features=Translate,AcceptCHFrame,...），用数组形式的ignoreDefaultArgs过滤它时，必须提供与当前版本完全一致的整条参数，实际中更稳妥的做法是通过args里的--disable-features/--enable-features让合并逻辑替你调整特性集合。
• 适用前提：以上参数清单对应当前仓库版本的源码（puppeteer-core的 Node 启动器）；defaultArgs的可用性与puppeteer完整包绑定（Node 环境、PuppeteerNode），具体行为以 packages/puppeteer-core/src/node/ChromeLauncher.ts 与 FirefoxLauncher.ts 的实际代码为准。

【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer