# Proxy Rewrite 配置选项

proxy-rewrite 插件提供灵活的选项，用于改写 API 网关转发到上游服务的请求，从而改进 API 管理。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

请参阅[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)了解所有插件可用的配置选项。

* uri

  string

  ***

  新的上游 URI 路径。值可以是[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

* 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`。

* set\_ngx\_uri

  boolean

  默认值：`false`

  ***

  API7 网关 3.9.21 和 3.10.8 支持此字段。APISIX 3.19.0 不提供此字段；当 `use_real_request_uri_unsafe` 为 false 时，APISIX 3.19.0 会将 `ngx.var.uri` 更新为重写后的上游 URI。

  在 API7 网关中，当 `use_real_request_uri_unsafe` 为 false 时，如果 `set_ngx_uri` 为 false，`ngx.var.uri` 会保留原始的规范化请求 URI；如果 `set_ngx_uri` 为 true，则更新为重写后的上游 URI。当 `use_real_request_uri_unsafe` 为 true 时，两种产品都不会更新 `ngx.var.uri`。

* host

  string

  ***

  设置 [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) 请求头。

* headers

  object

  ***

  要执行的请求头动作。可以设置为动作动词 `add`、`remove` 和/或 `set` 的对象；或由要 `set` 的请求头组成的对象。

  配置多个操作时，按 `add`、`set`、`remove` 的顺序执行。对于同一个请求头，`set` 会覆盖 `add` 添加的值，`remove` 会在这两项操作之后删除该请求头。

  * add

    object

    ***

    追加到请求的请求头。如果请求中已存在该请求头，则将追加该请求头值。请求头值可以设置为常量、一个或多个[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)，或使用 `$1-$2-$3` 等变量的 `regex_uri` 匹配结果。

    请求头值也可以是数组。每个值都会独立解析，并按数组顺序追加为单独的请求头行。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。

  * set

    object

    ***

    设置到请求的请求头。如果请求中已存在该请求头，则将覆盖该请求头值。请求头值可以设置为常量、一个或多个[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)，或使用 `$1-$2-$3` 等变量的 `regex_uri` 匹配结果。

    请求头值也可以是数组。每个值都会独立解析，且该数组会按数组顺序生成单独的请求头行，并替换任何现有值。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。

    不应用于设置 `Host`。

  * remove

    array\[string]

    ***

    从请求中删除的请求头。

* use\_real\_request\_uri\_unsafe

  boolean

  默认值：`false`

  ***

  如果为 true，则绕过 URI 规范化并允许完整的原始请求 URI。启用此选项被认为是不安全的。
