如何用declarativeNetRequest规则在单次请求中添加HTTP头与查询参数？

问题 #

在Manifest V2中，可通过webRequest API获取事件序列，能轻松拦截请求、修改请求头、追加查询参数后重定向到构造好的URL，最终仅产生一个包含所有修改（含修改后的请求头与新增查询参数）的重定向请求。

尝试在Manifest V3中使用declarativeNetRequest API实现相同功能时遇到问题，当前定义了两个动态规则：

addParameterToRequest: {
  addRules: [
    {
      id: 1,
      priority: 1,
      action: {
        type: 'redirect',
        redirect: {
          transform: {
            queryTransform: {
              addOrReplaceParams: [{key: data.key, value: data.value}],
            },
          },
        },
      },
      condition: {
        urlFilter: data.urlPattern,
        resourceTypes: ['main_frame'],
      },
    },
  ],
  removeRuleIds: [1],
},
addCookie: {
  addRules: [
    {
      id: 3,
      priority: 1,
      action: {
        type: 'modifyHeaders',
        responseHeaders: [
          {header: 'Cookie', operation: 'append', value: data.value},
        ],
      },
      condition: {
        urlFilter: data.urlPattern,
        resourceTypes: ['main_frame'],
      },
    },
  ],
  removeRuleIds: [3],
}

但在MV3中会产生两次请求：一次是追加查询参数的重定向请求，另一次是带有修改后请求头的原URL请求。

Manifest V2结果：

• 原URL = https://localhost/route
• 修改后URL = 重定向至https://localhost/route?qparam=value，且Cookie请求头已追加值

Manifest V3结果：

• 原URL = https://localhost/route
• 修改后URL #1 = 重定向至https://localhost/route?qparam=value
• 修改后URL #2 = https://localhost/route，且Cookie请求头已追加值

尝试合并规则、调整优先级均无效，始终产生两次请求。如何在MV3中实现与MV2相同的单次请求完成所有修改的功能？

解决方案 #

1. 合并规则并调整作用时机 #

问题核心是当前的modifyHeaders规则作用于响应头，且两个规则分别触发导致请求拆分。需要把修改请求头和重定向合并到一个规则中，并且确保请求头修改作用于请求阶段：

const combinedRule = {
  addRules: [
    {
      id: 1,
      priority: 10, // 提高优先级确保规则先触发
      action: [
        {
          type: 'modifyHeaders',
          requestHeaders: [ // 修改为requestHeaders而非responseHeaders
            {header: 'Cookie', operation: 'append', value: data.value},
          ],
        },
        {
          type: 'redirect',
          redirect: {
            transform: {
              queryTransform: {
                addOrReplaceParams: [{key: data.key, value: data.value}],
              },
            },
          },
        },
      ],
      condition: {
        urlFilter: data.urlPattern,
        resourceTypes: ['main_frame'],
      },
    },
  ],
  removeRuleIds: [1],
};

2. 关键调整点 #

• 将modifyHeaders的目标从responseHeaders改为requestHeaders：这样修改会作用于原始请求的发送阶段，而非响应返回阶段
• 把两个动作合并到同一个规则的action数组中：MV3支持单个规则包含多个动作，会按顺序执行
• 提高规则优先级：避免其他规则干扰，确保该规则优先匹配执行

3. 验证逻辑 #

合并后的规则会对匹配的原始请求先修改请求头（追加Cookie），再执行重定向到带查询参数的URL，最终浏览器只会发送一次修改后的请求（带Cookie头和查询参数），和MV2的效果一致。

内容的提问来源于stack exchange，提问作者Michał J