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 查詢字串執行操作，模式取決於參數名稱的前綴或參數的數量。可以使用區塊一次指定多個操作，這些操作將按以下順序分組執行：rename 🡒 set 🡒 append 🡒 replace 🡒 delete。
- 如果沒有前綴，則會在查詢字串中設定具有給定值的參數。
  
  例如，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 查詢參數的值（值以 bar 開頭）替換為 baz

uri query foo ^(ba)r $1z

一次執行多個查詢操作

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