为何使用declarativeNetRequest的modifyHeaders仅在iframe中生效？

问题现象 #

开发Chrome扩展时，使用declarativeNetRequest API修改User-Agent请求头，发现只有iframe内的请求UA被修改，主框架页面的请求UA无变化。

原配置文件 #

manifest.json #

{
    "name": "My extension",
    "version": "1.0.0",
    "manifest_version": 3,
    "description": "My extension",
    "homepage_url": "http://example.com",
    "content_scripts": [
     {
         "matches": ["http://*/*", "https://*/*"],
         "css": ["style.css"],
         "js": ["script.js"]
     }
    ],
    "declarative_net_request": {
    "rule_resources": [{
      "id": "modify-user-agent",
      "enabled": true,
      "path": "rules.json"
    }]
  },
    "icons": {
        "16": "icons/icon16.png",
        "48": "icons/icon48.png",
        "128": "icons/icon128.png"
    },
    "web_accessible_resources": [{
        "resources": [
            "redirect.html"
        ],
        "matches": [
            "*://*/*"
        ]
    }],
    "action":
    {
        "default_icon": "icons/icon48.png",
        "default_popup": "./src/index.html"
    },
    "default_locale": "en",
    "permissions": [
        "contentSettings",
        "tabs",
        "storage",
        "declarativeNetRequest",
        "declarativeNetRequestWithHostAccess"
    ],
    "host_permissions": [
    "*://*/*"
  ]
}

rules.json #

[{
    "id": 1,
    "priority": 1,
    "action": {
        "type": "modifyHeaders",
        "requestHeaders": [{
            "header": "User-Agent",
            "operation": "set",
            "value": "My User Agent"
      }]
    },
    "condition": {
        "urlFilter": "*://*/*"
    }
}]

解决方法 #

在规则的condition字段中显式添加resourceTypes，指定要匹配的资源类型：

"resourceTypes": ["main_frame", "sub_frame"]

修改后，主框架页面和iframe的请求UA都能被正常修改。

原因解析 #

当未指定resourceTypes时，declarativeNetRequest的规则默认仅匹配部分资源类型，其中包含sub_frame（iframe请求），但不包含main_frame（主框架页面请求），这就是默认情况下只有iframe的UA被修改的原因。

虽然官方文档对默认值的描述不够直观，但实际上，未设置resourceTypes时，规则会匹配除main_frame、object、media之外的大部分资源类型。如果需要对主框架请求生效，必须显式声明main_frame类型。

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