Puppeteer 中 DownloadBehavior 详解：控制浏览器文件下载策略与保存路径

本文基于 Puppeteer 官方 API 文档中的 DownloadBehavior 接口，完整讲解该接口的签名、policy 与 downloadPath 两个属性的取值与约束，并结合仓库源码说明它在 CDP 与 WebDriver BiDi 两种协议下的实际落地方式。读完本文，你可以在 puppeteer.launch、puppeteer.connect 以及 browser.createBrowserContext 中正确配置下载行为，让被测页面的文件下载被允许、拒绝，或按下载 GUID 自动命名，并理解各浏览器/协议组合下的能力边界。

接口定义与签名

DownloadBehavior 是 Puppeteer 用于描述"浏览器在遇到文件下载请求时如何处理"的公共接口，定义于 DownloadBehavior.ts，并通过 common.ts 统一导出。其签名为：

export interface DownloadBehavior {
  policy: DownloadPolicy;
  downloadPath?: string;
}

其中 DownloadPolicy 是一个联合类型（见 puppeteer.downloadpolicy.md 与源码）：

export type DownloadPolicy = 'deny' | 'allow' | 'allowAndName' | 'default';

也就是说，一个 DownloadBehavior 配置由"策略（policy）+ 可选的保存路径（downloadPath）"两部分组成，整体表达"允许还是拒绝下载，以及文件存到哪里"。

属性一：policy

policy 为必填字段（string 联合类型，非 optional），决定下载请求的整体处理方式：

取值	含义
'deny'	拒绝所有下载请求，文件不会被保存
'allow'	允许下载，文件保存至 downloadPath 指定目录，保留原始文件名
'allowAndName'	允许下载，且所有文件按其下载 GUID 命名（避免文件名冲突或保留原始名字），同样需要 downloadPath
'default'	使用浏览器自身默认可用的行为（如弹出"另存为"或直接走系统默认下载）

接口文档中的备注明确指出：将策略设为 allowAndName 时，所有文件都会根据其下载 guid 命名（"Setting this to allowAndName will name all files according to their download guids"）。在需要批量、可编程地收集下载产物的场景（如自动化流水线拉取报表文件）中，基于 GUID 的文件名可以稳定地区分每一次下载，而不依赖页面给出的原始文件名。

属性二：downloadPath

downloadPath 是可选的 string 字段，表示"下载文件默认保存到的路径"。接口备注给出了硬性约束：

Setting this is required if behavior is set to allow or allowAndName.

即：当 policy 为 allow 或 allowAndName 时，downloadPath 必须提供；而 deny 场景下该字段无实际意义（测试用例中仍传了一个值，但被拒绝的策略使下载根本不发生）。

在哪些入口可以配置 DownloadBehavior

结合源码可以确认，DownloadBehavior 有三个主要注入入口：

1. launch / connect 的全局选项

downloadBehavior 是通用浏览器选项接口 ConnectOptions 的成员（见 ConnectOptions.ts）：

/**
 * Sets the download behavior for the context.
 */
downloadBehavior?: DownloadBehavior;

由于 LaunchOptions 继承自 ConnectOptions（见 LaunchOptions.ts），puppeteer.launch() 与 puppeteer.connect() 都接受该字段。在 CDP 实现中，浏览器附加（attach）阶段会把它应用到默认浏览器上下文，见 cdp/Browser.ts：

async _attach(downloadBehavior: DownloadBehavior | undefined): Promise<void> {
  // ...
  if (downloadBehavior) {
    await this.#defaultContext.setDownloadBehavior(downloadBehavior);
  }
  // ...
}

即：启动时传入的 downloadBehavior 作用于 browser.defaultBrowserContext() 上的所有页面。

2. 为独立浏览器上下文单独配置

BrowserContextOptions（见 api/Browser.ts）同样包含该字段：

export interface BrowserContextOptions {
  proxyServer?: string;
  proxyBypassList?: string[];
  /**
   * Behavior definition for when downloading a file.
   *
   * @remarks
   * If not set, the default behavior will be used.
   */
  downloadBehavior?: DownloadBehavior;
}

文档备注说明：如果不设置，则使用默认行为。CDP 侧在 createBrowserContext 中处理该选项（cdp/Browser.ts）：

const {proxyServer, proxyBypassList, downloadBehavior} = options;
// ... 创建 context 之后
if (downloadBehavior) {
  await context.setDownloadBehavior(downloadBehavior);
}

这使得"默认上下文保持浏览器原行为、隔离上下文强制允许并下载到指定目录"成为可能，是测试与生产环境常见的配置方式。

3. WebDriver BiDi 协议下的处理

BiDi 实现位于 bidi/core/Browser.ts，在 createUserContext 中按策略分支处理：

if (options.downloadBehavior?.policy === 'allowAndName') {
  throw new UnsupportedOperation(
    '`allowAndName` is not supported in WebDriver BiDi',
  );
}
if (options.downloadBehavior?.policy === 'allow') {
  if (options.downloadBehavior.downloadPath === undefined) {
    throw new UnsupportedOperation(
      '`downloadPath` is required in `allow` download behavior',
    );
  }
  await this.session.send('browser.setDownloadBehavior', {
    downloadBehavior: {
      type: 'allowed',
      destinationFolder: options.downloadBehavior.downloadPath,
    },
    userContexts: [userContext],
  });
}
if (options.downloadBehavior?.policy === 'deny') {
  await this.session.send('browser.setDownloadBehavior', {
    downloadBehavior: {type: 'denied'},
    userContexts: [userContext],
  });
}

由此可以确认两条重要的能力边界：

1. allowAndName 在 WebDriver BiDi 下不被支持，会抛出 UnsupportedOperation 错误；
2. allow 策略下若缺少 downloadPath，同样直接抛错——这与接口文档中"allow/allowAndName 必须提供 downloadPath"的备注一致，BiDi 实现把文档约束变成了运行时的强校验。

底层协议调用链

CDP 协议

CDP 上下文中的 setDownloadBehavior 直接把接口字段映射为 CDP 命令 Browser.setDownloadBehavior（见 cdp/BrowserContext.ts）：

public async setDownloadBehavior(
  downloadBehavior: DownloadBehavior,
): Promise<void> {
  await this.#connection.send('Browser.setDownloadBehavior', {
    behavior: downloadBehavior.policy,
    downloadPath: downloadBehavior.downloadPath,
    browserContextId: this.#id,
  });
}

可以看出字段的一一对应关系：policy 映射为 behavior、downloadPath 映射为 downloadPath，并附带 browserContextId 以限定生效范围——这也是"per-context 生效"的实现基础。

BiDi 协议

BiDi 侧则映射到 browser.setDownloadBehavior 方法：allow → {type: 'allowed', destinationFolder: ...}，deny → {type: 'denied'}，并通过 userContexts 限定到具体用户上下文。

实战示例：允许与拒绝下载

仓库的测试用例 test/src/download.test.ts 演示了完整的端到端用法，覆盖 allow 与 deny 两种策略：

import {mkdtemp, rm} from 'node:fs/promises';
import {tmpdir} from 'node:os';
import {join} from 'node:path';

// 每个用例创建独立临时目录
let tempDir: string;

beforeEach(async () => {
  tempDir = await mkdtemp(join(tmpdir(), 'downloads-'));
});

afterEach(async () => {
  await rm(tempDir, {recursive: true, force: true});
});

// 用例 1：allow —— 文件应落入指定目录
it('should download to configured location', async () => {
  const {browser, server} = await getTestState({skipContextCreation: true});

  using context = await browser.createBrowserContext({
    downloadBehavior: {
      policy: 'allow',
      downloadPath: tempDir,
    },
  });
  const page = await context.newPage();
  await page.goto(server.PREFIX + '/download.html');
  await page.click('#download');
  await waitForFileExistence(join(tempDir, 'download.txt'));
});

// 用例 2：deny —— 同一页面操作不应产生文件
it('should not download to location', async () => {
  const {browser, server} = await getTestState({skipContextCreation: true});

  using context = await browser.createBrowserContext({
    downloadBehavior: {
      policy: 'deny',
      downloadPath: '/tmp',
    },
  });
  const page = await context.newPage();
  await page.goto(server.PREFIX + '/download.html');
  await page.click('#download');
  await expect(
    waitForFileExistence(join(tempDir, 'download.txt')),
  ).rejects.toThrow();
});

这两个用例印证了接口文档的语义：

• 配置 policy: 'allow' 且给出 downloadPath 后，触发 <a download> 下载，文件 download.txt 会真实落入 downloadPath 目录；
• 配置 policy: 'deny' 后执行相同的下载操作，目标目录中不会出现文件（waitForFileExistence 抛错）；
• 测试还展示了工程上的常见做法：用 mkdtemp 在系统临时区创建一次性下载目录，测试结束即清理，避免污染工作目录。

对应地，在启动整个浏览器时也可以写成：

const browser = await puppeteer.launch({
  downloadBehavior: {
    policy: 'allow',
    downloadPath: '/path/to/downloads',
  },
});

或连接已运行的浏览器时（puppeteer.connect 同样接受 downloadBehavior，因为它属于 ConnectOptions）：

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://localhost:9222/devtools/browser',
  downloadBehavior: {policy: 'deny'},
});

使用建议与适用前提

基于以上源码与测试证据，可以归纳出几条实践要点：

1. allow / allowAndName 必须搭配 downloadPath。BiDi 实现会显式抛错（见上文 bidi/core/Browser.ts 的运行时校验）；CDP 侧虽然直接透传给 Browser.setDownloadBehavior，但按接口备注，缺少路径时行为不可预期，应始终显式提供。
2. 需要可编程、无歧义的文件名时选择 allowAndName：文件以下载 GUID 命名，适合自动化产物收集；但注意该策略仅适用于 CDP 协议，在 WebDriver BiDi（例如 Firefox 默认协议）下会抛出 UnsupportedOperation。
3. 策略生效范围是浏览器上下文：launch/connect 传入的配置作用于默认上下文（CDP 实现中应用到 #defaultContext），而 createBrowserContext({downloadBehavior}) 只影响新建的隔离上下文；不设置时保持浏览器默认行为。
4. 适用前提：本接口是协议级的下载策略控制，与 Page.waitForFileChooser 这类"文件选择器（file chooser）"机制是不同场景——前者针对浏览器触发的文件下载（如 <a download>、Content-Disposition 响应），后者针对 <input type="file"> 的上传选择框，不要混用。

参考文档：puppeteer.downloadbehavior.md、puppeteer.downloadpolicy.md。