Puppeteer调用browser.downloads.download报TypeError undefined报错

你使用的browser.downloads.download 是Chrome 扩展的专属API，并非Puppeteer 提供的封装能力。Puppeteer 实例化得到的Browser对象本身不存在downloads属性，访问browser.downloads时就会返回undefined，再取它的.download方法自然会抛出你遇到的类型错误。
你参考的MDN文档对应的是WebExtension 扩展的下载接口，和Puppeteer 控制普通浏览器的运行上下文完全不互通。

按照Puppeteer的原生能力，批量下载的完整逻辑可以按下面的方式调整：

• 启动浏览器时配置必要参数，避免下载流程被拦截
  启动参数追加--disable-popup-blocking，允许页面触发的下载弹窗正常执行：

  const browser = await puppeteer.launch({
    headless: false,
    args: ['--start-maximized', '--disable-popup-blocking'],
    defaultViewport: null,
  });
  

• 提前配置页面的下载行为，指定本地下载存储路径，绑定下载状态监听
  替换原来写的browser.downloads相关逻辑，在拿到所有链接、准备触发下载之前完成配置：

  const path = require('path');
  // 替换为你实际需要的本地下载目录
  const downloadDir = path.resolve(__dirname, './target_downloads');
  // 通过CDP协议配置下载行为
  await page.createCDPSession().then(async (cdp) => {
    await cdp.send('Browser.setDownloadBehavior', {
      behavior: 'allowAndName',
      downloadPath: downloadDir,
      eventsEnabled: true,
    });
    // 监听下载进度事件
    cdp.on('Browser.downloadProgress', (event) => {
      if (event.state === 'completed') {
        console.log(`下载完成，文件ID：${event.guid}`);
      }
      if (event.state === 'failed') {
        console.log(`下载失败，文件ID：${event.guid}`);
      }
    });
  });
  

• 触发批量下载动作
  你已经获取了所有带完整登录态的下载链接，不需要手动构造独立请求，直接在页面上下文里触发原生下载流程，避免出现鉴权失效、跨域拦截的问题：

  // 替换原来的forEach循环里的错误下载逻辑
  for (const link of finalArray) {
    await page.evaluate((url) => {
      // 动态创建a标签触发下载
      const downloadLink = document.createElement('a');
      downloadLink.href = url;
      downloadLink.style.display = 'none';
      document.body.appendChild(downloadLink);
      downloadLink.click();
      downloadLink.remove();
      // 间隔1.5秒触发下一个，避免下载队列拥堵
      return new Promise(resolve => setTimeout(resolve, 1500));
    }, link);
  }
  

• 修复原有代码的逻辑漏洞
  原来代码里的page.waitForTimeout(500_000)没有加await，会被直接跳过，导致程序提前退出、中断下载流程，需要改成：

  await page.waitForTimeout(500_000);
  

• 如果需要跑无头模式，要使用Puppeteer 18+ 提供的headless: 'new'配置，旧版无头模式存在下载功能兼容问题。
• 所有下载事件的监听绑定必须在触发下载动作之前完成，否则会漏接下载完成/失败的回调。
• 如果平台对下载链接有防盗链校验，优先走页面内触发点击的下载逻辑，不要脱离页面上下文独立发请求，否则大概率会被接口拦截。
• 你原来的Promise写法存在本质错误：downloading.then(onStartedDownload(link), onFailed(link)) 会在循环执行时立刻调用两个回调函数，不会等待下载Promise的状态变化，就算browser.downloads存在，这段逻辑也跑不通。正确的Promise回调写法需要传入函数引用，比如downloading.then(() => onStartedDownload(link), (err) => onFailed(err, link))。

内容的提问来源于stack exchange，提问作者Andrea D_