大网数据广告活动
Web 标准与前端开发

`network.setExtraHeaders` command

· 52CE 我爱测

The `network.setExtraHeaders` command of the `network` module specifies headers that the browser adds to the requests it sends, replacing any existing header with the same name. The headers apply to requests from all contexts or from the specified user contexts or top-level conte

The network.setExtraHeaders command of the network module specifies headers that the browser adds to the requests it sends, replacing any existing header with the same name. The headers apply to requests from all contexts or from the specified user contexts or top-level contexts.

Syntax

/* With required parameters */
{
  "method": "network.setExtraHeaders",
  "params": {
    "headers": [
      {
        "name": "X-Test-Run",
        "value": {
          "type": "string",
          "value": "checkout-flow"
        }
      }
    ]
  }
}

/* With the optional `contexts` parameter */
{
  "method": "network.setExtraHeaders",
  "params": {
    "contexts": ["93ee5bd6-d256-4608-a002-9a8995cc0e5f"],
    "headers": [
      {
        "name": "X-Test-Run",
        "value": {
          "type": "string",
          "value": "checkout-flow"
        }
      }
    ]
  }
}

/* With the optional `userContexts` parameter */
{
  "method": "network.setExtraHeaders",
  "params": {
    "headers": [
      {
        "name": "X-Test-Run",
        "value": {
          "type": "string",
          "value": "checkout-flow"
        }
      }
    ],
    "userContexts": ["4e4b1f6d-3f1a-4b2e-9f8c-1a2b3c4d5e6f"]
  }
}

Parameters

The params field contains:

  • contexts

    • : An array of one or more context ID strings, each identifying a top-level context whose requests include the specified headers. Requests from their child contexts, such as iframes, also include these headers. Context IDs are returned by commands such as browsingContext.getTree.

      This field cannot be used if userContexts is also specified.

  • headers

    • : An array of objects, each specifying a header to add to requests. The array replaces the headers previously set for the same contexts, the same user contexts, or for all contexts. Specify an empty array to remove the previously set headers.

      Each object contains the following fields:

      • name
        • : A string that contains the header name, such as X-Test-Run. It must be a valid HTTP header name.
      • value
        • : An object that specifies the header value. It contains the following fields:
          • type
            • : A string that specifies how the header value is encoded. It can take one of the following values:
              • base64: The value is Base64-encoded bytes.
              • string: The value is text, which the browser sends encoded as UTF-8 bytes.
          • value
            • : A string that contains the header value in the encoding specified by the type field. The decoded header value cannot contain line breaks or null characters, or start or end with a space or tab.
  • userContexts

If neither contexts nor userContexts is specified, the headers are added to requests from all contexts.

Return value

The result field in the response is an empty object ({}).

Errors

  • invalid argument
    • : Thrown in any of the following cases:
      • A required parameter is missing, or a parameter has an invalid type.
      • The type field in a header's value object is not base64 or string.
      • Both contexts and userContexts are specified.
      • contexts or userContexts is specified but empty.
      • A header name is invalid.
      • A header value is invalid.
      • A context specified in contexts is not a top-level context.
  • no such frame
    • : No context with an ID specified in contexts is found.
  • no such user context
    • : No user context with an ID specified in userContexts is found.

Description

When you send the network.setExtraHeaders command, the browser adds the specified headers to all requests from the selected contexts or user contexts, or from all contexts if neither contexts nor userContexts is specified. These include navigation requests and requests made by scripts, such as with Window/fetch. The headers are added before the browser emits the network.beforeRequestSent event, so the headers array in the event's request object already includes them.

Each call to network.setExtraHeaders replaces the previously set headers only for the specified contexts or user contexts, or for all contexts if neither parameter is specified. For example, changing the headers for one tab doesn't remove the headers set for its user context.

Headers set for all contexts or for a user context also apply to contexts created after the command is processed. Headers set for a top-level context also apply to child contexts created within it later. The headers stay in effect until you replace them with another network.setExtraHeaders command or until the session ends.

A header you specify replaces any existing header with the same name that the browser would otherwise send. The browser doesn't add to the existing value. For example, specifying Accept-Language with the value de-DE replaces the browser's existing value, such as en-US,en;q=0.9.

The browser combines the headers you specify for all contexts, for a user context, and for a top-level context within the same session. If you set the same header for more than one of these, the most specific value is sent: a value set for the top-level context wins over a value set for the user context, which wins over a value set for all contexts.

Examples

Adding a header to every request

Assume you have a WebDriver BiDi connection and an active session.

Assume also that two tabs are open, both showing the page you're testing. You got the first tab's context ID using browsingContext.getTree. You created a user context using browser.createUserContext, which returned its ID. You then opened the second tab in that user context using browsingContext.create.

Suppose your test server logs requests, and you want to identify the test responsible for each request. Send the following message to add an X-Test-Run header to requests from all contexts:

{
  "id": 1,
  "method": "network.setExtraHeaders",
  "params": {
    "headers": [
      {
        "name": "X-Test-Run",
        "value": {
          "type": "string",
          "value": "checkout-flow"
        }
      }
    ]
  }
}

The browser responds with an empty result object:

{
  "id": 1,
  "type": "success",
  "result": {}
}

From then on, every request from every tab carries the X-Test-Run: checkout-flow header. If you're subscribed to network.beforeRequestSent, the header also appears in the headers array of each event's request object.

Overriding a header value for a user context

Using the same connection, session, and tabs as in the first example, suppose you replace the headers for all contexts with two headers, X-Test-Run: checkout-flow and X-Tenant: tenant-b, using a single network.setExtraHeaders command.

Send the following message to set a different X-Tenant value for requests from the second tab's user context:

{
  "id": 2,
  "method": "network.setExtraHeaders",
  "params": {
    "headers": [
      {
        "name": "X-Tenant",
        "value": {
          "type": "string",
          "value": "tenant-a"
        }
      }
    ],
    "userContexts": ["4e4b1f6d-3f1a-4b2e-9f8c-1a2b3c4d5e6f"]
  }
}

The browser responds with an empty result object:

{
  "id": 2,
  "type": "success",
  "result": {}
}

Requests from the second tab now carry X-Test-Run: checkout-flow and X-Tenant: tenant-a. Requests from the first tab still carry X-Test-Run: checkout-flow and X-Tenant: tenant-b.

Replacing a request header for one tab

Using the same connection, session, and tabs as in the first example, suppose you want to check how a page responds to a user whose preferred language is Canadian French.

Send the following message to replace the Accept-Language header for the first tab:

{
  "id": 3,
  "method": "network.setExtraHeaders",
  "params": {
    "contexts": ["93ee5bd6-d256-4608-a002-9a8995cc0e5f"],
    "headers": [
      {
        "name": "Accept-Language",
        "value": {
          "type": "string",
          "value": "fr-CA"
        }
      }
    ]
  }
}

The browser responds with an empty result object:

{
  "id": 3,
  "type": "success",
  "result": {}
}

Requests from that tab now carry Accept-Language: fr-CA instead of the value the browser would otherwise send, such as en-US,en;q=0.9.

Removing the headers set for all contexts

Using the same connection and session as in the first example, send the following message with an empty headers array to remove the headers set for all contexts:

{
  "id": 4,
  "method": "network.setExtraHeaders",
  "params": {
    "headers": []
  }
}

The browser responds with an empty result object:

{
  "id": 4,
  "type": "success",
  "result": {}
}

From then on, requests no longer carry the X-Test-Run header. Headers set for specific user contexts or top-level contexts are not affected. To remove those headers, send an empty headers array and include the corresponding IDs in userContexts or contexts.

Specifications

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。