如何在MV3版Chrome扩展中从外部URL下载文件？

问题场景 #

使用Chrome扩展MV3开发，向页面注入下载按钮后，点击按钮Chrome会直接在当前标签页打开外部URL的PDF文件，而非触发本地下载。已在manifest.json中配置downloads权限，但问题依旧。

原因分析 #

页面上下文的<a>标签download属性受跨域限制：当目标资源域名与当前页面域名不一致时，浏览器会忽略download属性，默认以预览方式打开资源。Content script运行在页面隔离环境中，无法绕过这个限制。

解决方案 #

利用Chrome扩展的downloads特权API，通过后台Service Worker处理下载请求，步骤如下：

1. 修改Content Script代码 #

将原有的<a>标签替换为按钮，点击时向后台发送下载请求：

function createModal() {
  var auroraModal = document.createElement('div');
  auroraModal.className = '_aurora__modal';
  auroraModal.id = '_aurora__modal';

  // 替换a标签为按钮，添加点击事件
  var downloadBtn = document.createElement('button');
  downloadBtn.textContent = 'Download';
  downloadBtn.addEventListener('click', () => {
    chrome.runtime.sendMessage({
      type: 'DOWNLOAD_PDF',
      url: 'https://www.africau.edu/images/default/sample.pdf',
      filename: 'Example.pdf'
    });
  });

  auroraModal.innerHTML = '<p>Woo-hoo <strong>'+dataFromPromise+'</strong>! Your custom PDF is ready!</p>';
  auroraModal.appendChild(downloadBtn);
  document.body.appendChild(auroraModal);
}

2. 配置后台Service Worker #

在background/index.js中添加消息监听，调用downloads.download API触发下载：

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'DOWNLOAD_PDF') {
    chrome.downloads.download({
      url: message.url,
      filename: message.filename,
      conflictAction: 'uniquify' // 可选：文件名重复时自动添加后缀
    }, (downloadId) => {
      if (chrome.runtime.lastError) {
        console.error('下载失败:', chrome.runtime.lastError);
      }
    });
  }
});

3. 确认Manifest配置 #

确保manifest.json中已正确声明downloads权限（你当前的配置已满足）：

{
  "permissions": ["storage", "tabs", "downloads"],
  // 其他配置...
}

原理说明 #

Chrome扩展的downloadsAPI属于特权接口，不受页面跨域规则限制，直接由浏览器层面处理下载请求，能强制触发文件保存行为，而非预览。

内容的提问来源于stack exchange，提问作者Noah Valens