Chrome扩展Manifest V3：chrome.downloads API无法暂停小文件下载

问题描述 #

在Chrome扩展Manifest V3环境下，尝试在文件下载完成前暂停任务（用于分析后重启下载），通过chrome.downloads.onDeterminingFileName事件检测下载启动，并在事件处理器中调用chrome.downloads.pause方法暂停下载。

使用的代码示例：

chrome.downloads.onDeterminingFileName.addListener(function (downloadItem) {
    if(downloadItem.fileSize < 20971520 && downloadItem.filename.endsWith('.exe') ){
        chrome.downloads.pause(downloadItem.id);
        console.log(downloadItem.id);
    }
});

遇到的问题：该逻辑对小于1MB的小文件无效，文件会直接完成下载；但对较大文件能正常触发暂停。

解决办法 #

小文件无法暂停的核心原因是：小文件下载速度极快，onDeterminingFileName事件触发并执行pause方法前，下载流程已经完成。针对这个时序问题，可通过以下方案解决：

1. 更早触发事件+轮询确认暂停状态 #

使用chrome.downloads.onCreated事件（下载任务刚创建时触发，比onDeterminingFileName更早），并结合轮询检查下载状态，确保暂停操作生效：

chrome.downloads.onCreated.addListener(async (downloadItem) => {
    // 匹配小于1MB的exe文件
    if (downloadItem.fileSize < 1048576 && downloadItem.filename.endsWith('.exe')) {
        // 立即尝试暂停
        await chrome.downloads.pause(downloadItem.id);
        
        // 轮询检查状态，兜底处理下载已完成的情况
        const checkInterval = setInterval(async () => {
            const [updatedItem] = await chrome.downloads.search({ id: downloadItem.id });
            if (!updatedItem) {
                clearInterval(checkInterval);
                return;
            }
            
            if (updatedItem.state === 'paused') {
                clearInterval(checkInterval);
                // 在这里执行你的文件分析逻辑
                // 分析完成后重启下载：await chrome.downloads.resume(downloadItem.id);
            } else if (updatedItem.state === 'complete') {
                clearInterval(checkInterval);
                // 若已完成，可选择删除文件后重新发起下载，或直接处理已下载文件
                // await chrome.downloads.removeFile(downloadItem.id);
                // 重新下载逻辑...
            }
        }, 10);
    }
});

2. 拦截请求并手动创建下载任务 #

通过chrome.webRequest提前拦截下载请求，手动创建下载任务并立即暂停，从根源上控制下载流程：

步骤1：配置Manifest权限

在manifest.json中添加必要权限：

{
    "permissions": ["downloads", "webRequest"],
    "host_permissions": ["<all_urls>"],
    "background": {
        "service_worker": "background.js"
    }
}

步骤2：实现拦截与手动下载逻辑

// 拦截exe文件的下载请求
chrome.webRequest.onBeforeRequest.addListener(
    async (details) => {
        if (details.url.endsWith('.exe')) {
            // 阻止默认下载行为
            return { cancel: true };
        }
    },
    { urls: ["<all_urls>"], types: ["download"] },
    ["blocking"]
);

// 手动创建下载任务并暂停
chrome.webRequest.onBeforeRequest.addListener(
    async (details) => {
        if (details.url.endsWith('.exe')) {
            // 手动创建下载任务
            const downloadId = await chrome.downloads.download({ url: details.url });
            // 立即暂停任务
            await chrome.downloads.pause(downloadId);
            
            // 执行文件分析逻辑
            // 分析完成后恢复下载：await chrome.downloads.resume(downloadId);
        }
    },
    { urls: ["<all_urls>"], types: ["download"] }
);

3. 使用挂起状态替代暂停 #

chrome.downloads.setSuspended方法可以将下载任务设置为挂起状态，比pause更强制，能更大概率拦截小文件下载：

chrome.downloads.onCreated.addListener(async (downloadItem) => {
    if (downloadItem.fileSize < 1048576 && downloadItem.filename.endsWith('.exe')) {
        // 设置任务为挂起状态
        await chrome.downloads.setSuspended(downloadItem.id, true);
        
        // 执行文件分析逻辑
        // 分析完成后取消挂起并恢复下载：
        // await chrome.downloads.setSuspended(downloadItem.id, false);
        // await chrome.downloads.resume(downloadItem.id);
    }
});

关键提示 #

• 时序问题是核心矛盾：小文件下载速度远快于事件回调的执行速度，必须通过更早的触发点或强制拦截来解决。
• 轮询检查是可靠的兜底方案，即使调用了暂停/挂起方法，也需要确认任务状态是否符合预期。
• 手动创建下载任务的方式可控性最强，但需要额外配置权限，且需注意Manifest V3中服务工作者的限制。

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