Chrome MV3中如何用declarativeNetRequest修改首个文档请求的User-Agent

核心问题在于chrome.tabs.onUpdated触发时机晚于首个文档请求，导致规则无法及时生效。可以通过更早触发的导航事件来解决：

关键思路 #

使用chrome.webNavigation.onBeforeNavigate事件——该事件在浏览器发起导航请求之前触发，能确保规则在首个请求发送前完成更新。同时配合chrome.tabs.onCreated处理新标签的首次加载场景。

步骤与代码实现 #

1. 更新Manifest权限 #

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

{
  "permissions": ["declarativeNetRequest", "storage", "tabs", "webNavigation"]
}

2. 替换事件监听逻辑 #

将原有的tabs.onUpdated监听替换为更早触发的事件，并封装规则更新逻辑：

// 封装规则更新函数，避免重复代码
function updateUserAgentRules(targetTabIds) {
  const ruleId = 1;
  chrome.declarativeNetRequest.updateSessionRules({
    removeRuleIds: [ruleId],
    addRules: [{
      id: ruleId,
      priority: 1,
      condition: {
        tabIds: targetTabIds,
        resourceTypes: ["main_frame", "sub_frame", "xmlhttprequest"],
      },
      action: {
        type: "modifyHeaders",
        requestHeaders: [{
          header: "user-agent",
          operation: "set",
          value: MY_USER_AGENT // 确保此处MY_USER_AGENT已正确定义
        }]
      }
    }]
  });
}

// 导航开始前更新规则，覆盖首个文档请求
chrome.webNavigation.onBeforeNavigate.addListener((details) => {
  chrome.storage.local.get(["tabs"], (result) => {
    const targetTabs = result.tabs || [];
    if (targetTabs.includes(details.tabId)) {
      updateUserAgentRules(targetTabs);
    }
  });
});

// 处理新标签创建场景，提前设置规则
chrome.tabs.onCreated.addListener((tab) => {
  chrome.storage.local.get(["tabs"], (result) => {
    const targetTabs = result.tabs || [];
    if (targetTabs.includes(tab.id)) {
      updateUserAgentRules(targetTabs);
    }
  });
});

// 保留tabs.onUpdated作为 fallback，处理特殊异常场景
chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
  if (changeInfo.status === 'loading') {
    chrome.storage.local.get(["tabs"], (result) => {
      const targetTabs = result.tabs || [];
      if (targetTabs.includes(tabId)) {
        updateUserAgentRules(targetTabs);
      }
    });
  }
});

3. 注意事项 #

• webNavigation.onBeforeNavigate是核心，确保规则在请求发起前生效；
• 规则优先级priority设置为1足够覆盖默认规则，若有其他自定义规则可适当调高；
• 确保MY_USER_AGENT变量已提前定义并赋值，避免出现未定义错误。

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