This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 24bc494e89 docs: correct header operation order in rewrite plugins
(#14196)
24bc494e89 is described below
commit 24bc494e898ac212520b172090032f6acfd87d30
Author: ruanweihong-aaa <[email protected]>
AuthorDate: Thu Nov 12 14:12:31 2026 +0800
docs: correct header operation order in rewrite plugins (#14196)
---
docs/en/latest/plugins/proxy-rewrite.md | 2 +-
docs/en/latest/plugins/response-rewrite.md | 8 ++++----
docs/zh/latest/plugins/proxy-rewrite.md | 2 +-
docs/zh/latest/plugins/response-rewrite.md | 8 ++++----
4 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/docs/en/latest/plugins/proxy-rewrite.md
b/docs/en/latest/plugins/proxy-rewrite.md
index d662cb5b24..a2103af1d4 100644
--- a/docs/en/latest/plugins/proxy-rewrite.md
+++ b/docs/en/latest/plugins/proxy-rewrite.md
@@ -44,7 +44,7 @@ The `proxy-rewrite` Plugin offers options to rewrite requests
that APISIX forwar
| method | string | False | | ["GET",
"POST", "PUT", "HEAD", "DELETE", "OPTIONS", "MKCOL", "COPY", "MOVE",
"PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] | HTTP method to rewrite
requests to use.
[...]
| regex_uri | array[string] | False | |
| Regular expressions used to
match the URI path from client requests and compose a new Upstream URI path.
When both `uri` and `regex_uri` are configured, `uri` has a higher priority.
Provide one or more pattern-replacement pairs in a flat array. The Plugin
evaluates pairs in order and a [...]
| host | string | False | |
| Set
[`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host)
request header.
[...]
-| headers | object | False | |
| Header actions to be executed. Can
be set to objects of action verbs `add`, `remove`, and/or `set`; or an object
consisting of headers to be `set`. When multiple action verbs are configured,
actions are executed in the order of `add`, `remove`, and `set`.
|
+| headers | object | False | |
| Header actions to be executed. Can
be set to objects of action verbs `add`, `remove`, and/or `set`; or an object
consisting of headers to be `set`. When multiple action verbs are configured,
actions are executed in the order of `add`, `set`, and `remove`. For the same
header, `set` overwr [...]
| headers.add | object | False | | | Headers
to append to requests. If a header is already present, its configured value is
appended. A value can be a constant, one or more [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or a
`regex_uri` capture such as `$1-$2-$3`. A value can also be an array. Each
element is resolved independently and appended as a separate header line in
array order. Array values are supported in APISIX 3.1 [...]
| headers.set | object | False | | | Headers
to set on requests. If a header is already present, its value is overwritten. A
value can be a constant, one or more [NGINX
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html), or a
`regex_uri` capture such as `$1-$2-$3`. A value can also be an array. Each
element is resolved independently, and the array replaces any existing value
with separate header lines in array order. Array values are supp [...]
| headers.remove | array[string] | False | | |
Headers to remove from requests.
diff --git a/docs/en/latest/plugins/response-rewrite.md
b/docs/en/latest/plugins/response-rewrite.md
index 74bc7beb75..ecb5dad55b 100644
--- a/docs/en/latest/plugins/response-rewrite.md
+++ b/docs/en/latest/plugins/response-rewrite.md
@@ -55,10 +55,10 @@ You can also use the [redirect](./redirect.md) Plugin to
set up redirects.
| status_code | integer | False | | [200, 598]
| New HTTP status code in the response. If unset, falls back to the original
status code.
|
| body | string | False | |
| New response body. The `Content-Length` header would also be reset. Should
not be configured with `filters`.
|
| body_base64 | boolean | False | false |
| If true, decode the response body configured in `body` before sending to
client, which is useful for image and protobuf decoding. Note that this
configuration cannot be used to decode Upstream response.
|
-| headers | object | False | |
| Actions to be executed in the order of `add`, `remove`, and `set`.
|
-| headers.add | array[string] | False | |
| Headers to append to requests. If a header already present in the
request, the header value will be appended. Header value could be set to a
constant, or one or more [Nginx
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html).
[...]
-| headers.set | object | False | |
| Headers to set to requests. If a header already present in the request, the
header value will be overwritten. Header value could be set to a constant, or
one or more [Nginx
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). |
-| headers.remove | array[string] | False | |
| Headers to remove from requests. |
+| headers | object | False | |
| Actions to be executed in the order of `add`, `set`, and `remove`. For the
same header, `set` overwrites values from `add`, and `remove` deletes the
header after both operations.
|
+| headers.add | array[string] | False | |
| Headers to append to responses. If a header already present in the
response, the header value will be appended. Header value could be set to a
constant, or one or more [Nginx
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html).
[...]
+| headers.set | object | False | |
| Headers to set to responses. If a header already present in the response,
the header value will be overwritten. Header value could be set to a constant,
or one or more [Nginx
variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). |
+| headers.remove | array[string] | False | |
| Headers to remove from responses. |
| vars | array[array] | False | | | An array of one or
more matching conditions in the form of
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) to
conditionally execute the Plugin. |
| filters | array[object] | False | |
| List of filters that modify the response body by replacing one
specified string with another. Should not be configured with `body`.
|
| filters.regex | string | True | |
| RegEx pattern to match on the response body. |
diff --git a/docs/zh/latest/plugins/proxy-rewrite.md
b/docs/zh/latest/plugins/proxy-rewrite.md
index 35d263de5d..fb86031350 100644
--- a/docs/zh/latest/plugins/proxy-rewrite.md
+++ b/docs/zh/latest/plugins/proxy-rewrite.md
@@ -44,7 +44,7 @@ description: proxy-rewrite 插件支持重写 APISIX 转发到上游服务的请
| method | string | 否 | | ["GET", "POST", "PUT", "HEAD", "DELETE", "OPTIONS",
"MKCOL", "COPY", "MOVE", "PROPFIND", "LOCK", "UNLOCK", "PATCH", "TRACE"] |
要使用的重写请求的 HTTP 方法。 |
| regex_uri | array[string] | 否 | | | 用于匹配客户端请求 URI 路径并生成新的上游 URI
路径的正则表达式。当同时配置 `uri` 和 `regex_uri` 时，`uri` 的优先级更高。请在一个扁平数组中提供一个或多个“匹配模式 -
替换值”配对。插件按顺序检查各配对，并应用第一个匹配项。例如，配置 `["^/test/(.*)/(.*)", "/$1-$2",
"^/other/(.*)", "/other"]` 后，发送到 `/test/user/agent` 的请求会被重写为 `/user-agent`，发送到
`/other/hello` 的请求会被重写为 `/other`。|
| host | string | 否 | | | 设置
[`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求标头。|
-| headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set`
的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照“添加”、“删除”和“设置”的顺序执行。|
+| headers | object | 否 | | | 要执行的标头操作。可以设置为动作动词 `add`、`remove` 和/或 `set`
的对象；或由要 `set` 的标头组成的对象。当配置了多个动作动词时，动作将按照 `add`、`set`、`remove`
的顺序执行。对于同名标头，`set` 会覆盖 `add` 添加的值，`remove` 会在这两个操作之后删除该标头。|
| headers.add | object | 否 | | | 要附加到请求的标头。如果请求中已经存在该标头，插件会追加配置值。值可以是常量、一个或多个
[NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者
`$1-$2-$3` 等 `regex_uri` 捕获结果。值也可以是数组；插件会分别解析每个元素，并按数组顺序将其追加为单独的标头行。APISIX
3.18.0 及后续版本支持数组值。|
| headers.set | object | 否 | | | 要在请求中设置的标头。如果请求中已经存在该标头，插件会覆盖原有值。值可以是常量、一个或多个
[NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)，或者
`$1-$2-$3` 等 `regex_uri` 捕获结果。值也可以是数组；插件会分别解析每个元素，并用按数组顺序生成的多个标头行替换原有值。APISIX
3.18.0 及后续版本支持数组值。请勿使用此字段设置 `Host`。|
| headers.remove | array[string] | 否 | | | 从请求中删除的标头。
diff --git a/docs/zh/latest/plugins/response-rewrite.md
b/docs/zh/latest/plugins/response-rewrite.md
index 0be097f853..5bce1b186f 100644
--- a/docs/zh/latest/plugins/response-rewrite.md
+++ b/docs/zh/latest/plugins/response-rewrite.md
@@ -54,10 +54,10 @@ description: response-rewrite 插件提供了重写 APISIX 及其上游服务返
| status_code | integer | 否 | | [200, 598] |
修改上游返回状态码，默认保留原始响应代码。
|
| body | string | 否 | | | 修改上游返回的
`body` 内容，如果设置了新内容，header 里面的 `Content-Length` 字段也会被去掉。
|
| body_base64 | boolean | 否 | false | | 如果为
true，则在发送到客户端之前解码`body` 中配置的响应主体，这对于图像和 protobuf 解码很有用。请注意，此配置不能用于解码上游响应。
|
-| headers | object | 否 | | | 按照 `add`、`remove` 和 `set` 的顺序执行的操作。 |
-| headers.add | array[string] | 否 | | |
要附加到请求的标头。如果请求中已经存在标头，则会附加标头值。标头值可以设置为常量，也可以设置为一个或多个 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。 |
-| headers.set | object | 否 | | |
要设置到请求的标头。如果请求中已经存在标头，则会覆盖标头值。标头值可以设置为常量，也可以设置为一个或多个 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。 |
-| headers.remove | array[string] | 否 | | | 要从请求中删除的标头。 |
+| headers | object | 否 | | | 按照 `add`、`set`、`remove` 的顺序执行的操作。对于同名标头，`set` 会覆盖
`add` 添加的值，`remove` 会在这两个操作之后删除该标头。 |
+| headers.add | array[string] | 否 | | |
要附加到响应的标头。如果响应中已经存在标头，则会附加标头值。标头值可以设置为常量，也可以设置为一个或多个 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。 |
+| headers.set | object | 否 | | |
要设置到响应的标头。如果响应中已经存在标头，则会覆盖标头值。标头值可以设置为常量，也可以设置为一个或多个 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。 |
+| headers.remove | array[string] | 否 | | | 要从响应中删除的标头。 |
| vars | array[array] | 否 | | | 以
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)
的形式包含一个或多个匹配条件的数组，用于有条件地执行插件。 |
| filters | array[object] | 否 | | | 通过将一个指定字符串替换为另一个指定字符串来修改响应主体的过滤器列表。不应与
`body` 一起配置。 |
| filters.regex | string | True | | | 用于匹配响应主体的 RegEx 模式。 |
