uri

操作请求的 URI。它可以删除路径前缀/后缀或在整个 URI 上替换子字符串。

此指令与 rewrite 不同，因为 uri 是_差异化_地更改 URI，而不是像 rewrite 那样将其重置为完全不同的内容。虽然 rewrite 被特殊处理为内部重定向，但 uri 只是另一个中间件。

语法

支持多种不同的操作：

uri [<matcher>] strip_prefix <target>
uri [<matcher>] strip_suffix <target>
uri [<matcher>] replace      <target> <replacement> [<limit>]
uri [<matcher>] path_regexp  <target> <replacement>
uri [<matcher>] query        [-|+]<param> [<value>]
uri [<matcher>] query {
	<param> [<value>] [<replacement>]
	...
}

第一个（非匹配器）参数指定操作：

strip_prefix 从路径中删除前缀。
strip_suffix 从路径中删除后缀。
replace 在整个 URI 上执行子字符串替换。
- <target> 是前缀、后缀或搜索字符串/正则表达式。如果是前缀，可以省略前导正斜杠，因为路径总是以正斜杠开头。
- <replacement> 是替换字符串。支持使用 $name 或 ${name} 语法的捕获组，或使用数字作为索引，例如 $1。有关详细信息，请参阅 Go 文档。如果替换值为 ""，则从值中删除匹配的文本。
- <limit> 是可选的最大替换次数限制。
path_regexp 在 URI 的路径部分执行正则表达式替换。
- <target> 是前缀、后缀或搜索字符串/正则表达式。如果是前缀，可以省略前导正斜杠，因为路径总是以正斜杠开头。
- <replacement> 是替换字符串。支持使用 $name 或 ${name} 语法的捕获组，或使用数字作为索引，例如 $1。有关详细信息，请参阅 Go 文档。如果替换值为 ""，则从值中删除匹配的文本。
query 对 URI 查询执行操作，模式取决于参数名称的前缀或参数数量。可以使用块一次指定多个操作，按此顺序分组和执行：重命名 🡒 设置 🡒 追加 🡒 替换 🡒 删除。
- 没有前缀时，参数在查询中设置为给定值。
  
  例如，uri query foo bar 将 foo 参数的值设置为 bar。
- 前缀为 - 时，从查询中删除参数。
  
  例如，uri query -foo 将从查询中删除 foo 参数。
- 前缀为 + 时，将参数追加到查询中，使用给定值。这_不会_覆盖具有相同名称的现有参数（省略 + 以覆盖）。
  
  例如，uri query +foo bar 将 foo=bar 追加到查询中。
- 参数中带有 > 作为中缀时，将参数重命名为 > 后面的值。
  
  例如，uri query foo>bar 将 foo 参数重命名为 bar。
- 有三个参数时，执行查询值正则表达式替换，其中第一个参数是查询参数名称，第二个是搜索值，第三个是替换值。第一个参数（参数名称）可以是 * 以对所有查询参数执行替换。
  
  支持使用 $name 或 ${name} 语法的捕获组，或使用数字作为索引，例如 $1。有关详细信息，请参阅 Go 文档。如果替换值为 ""，则从值中删除匹配的文本。
  
  例如，uri query foo ^(ba)r $1z 将替换 foo 参数的值，其中值以 bar 开头，结果值变为 baz。

URI 修改发生在 URI 的规范化或未转义形式上。但是，可以在前缀或后缀模式中使用转义序列，以仅匹配请求路径中这些位置的文字转义。例如，uri strip_prefix /a/b 将 /a/b/c 和 /a%2Fb/c 都重写为 /c；而 uri strip_prefix /a%2Fb 将 /a%2Fb/c 重写为 /c，但不会匹配 /a/b/c。

在修改之前，URI 路径会被清理掉目录遍历点。此外，多个斜杠（如 //）会被合并，除非 <target> 也包含多个斜杠。

类似指令

一些其他指令也可以操作请求 URI。

rewrite 将整个路径和查询更改为新值，而不是部分更改值。
handle_path 与 handle 相同，但在运行其处理程序之前，它会从请求中删除前缀。在许多情况下，可以使用它代替 uri strip_prefix 来消除一行额外的配置。

示例

从所有请求路径的开头删除 /api：

uri strip_prefix /api

从所有请求路径的末尾删除 .php：

uri strip_suffix .php

在任何请求 URI 中将 "/docs/" 替换为 "/v1/docs/"：

uri replace /docs/ /v1/docs/

将请求路径（但不是请求查询）中的所有重复斜杠折叠为单个斜杠：

uri path_regexp /{2,} /

将 foo 查询参数的值设置为 bar：

uri query foo bar

从查询中删除 foo 参数：

uri query -foo

将 foo 查询参数重命名为 bar：

uri query foo>bar

将 bar 参数追加到查询中：

uri query +foo bar

将 foo 查询参数的值替换为 baz，其中值以 bar 开头：

uri query foo ^(ba)r $1z

一次执行多个查询操作：

uri query {
	+foo bar
	-baz
	qux test
	renamethis>renamed
}