深入解析 Nginx location 匹配規則

最近公司專案設定 API Gateway 無法順利導向後端 API 位置。檢查 Azure 的配置時發現，Azure 的路由規則是有上下順序的，但 Nginx 並不是這樣運作。經過研究才發現 Nginx 的 location 匹配規則和 Azure API Gateway 的邏輯完全不同，這裡就做個完整整理。

核心匹配順序 (從高到低)

Nginx 在處理請求時，會遵循以下邏輯來決定最終使用的 location：

完整的演算法決策流程

如果我們把 Nginx 的「大腦」拆解成三個階段，邏輯會變得非常清晰：

第一階段：前綴字串比對 (Literal/Prefix Strings)

1. 檢查 = 精確匹配：如果有完全一致的 URI（例如 /index.html），直接採用並結束。
2. 尋找最長前綴：找出所有普通字串（包含無修飾與 ^~）中，匹配長度最長的那一個。
3. 判斷是否阻斷：
   • 如果這個「最長匹配」帶有 ^~ 修飾符，Nginx 認為這已經足夠明確，會直接採用此設定並停止搜尋。
   • 如果只是普通字串（無修飾），Nginx 會將此結果暫存起來作為備選方案，然後進入下一階段。

第二階段：正規表達式比對 (Regular Expressions)

1. 按順序掃描 ~ 或 ~*：從設定檔由上往下逐行讀取。
   • 只要有任何一個正規表達式成功匹配，就會立即採用此規則，並丟棄第一階段暫存的備選方案。

第三階段：最終終點

1. 保底機制：如果所有的正規表達式都沒有匹配成功，Nginx 才會最後採用第一階段暫存的最長普通前綴。

實戰範例與差異對比

透過以下配置，你可以清楚看到不同修飾符帶來的行為差異：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 精確匹配：最優先
location = / {
  # 只會匹配精確的 "/"
}

# 前綴阻斷：當它是最長前綴時，不進入後面的正規表達式
location ^~ /images/ {
  # 任何以 /images/ 開頭的請求都會停在這裡
}

# 普通前綴：作為「備胎」
location / {
  # 如果沒有更精確的匹配或符合下方的正規表達式，才會進入這裡
}

# 正規表達式：按順序比對
location ~* \.(gif|jpg|jpeg)$ {
  # 只有在上方都沒有命中時，才會由此規則處理圖片
}

參考: - nginx location 匹配規則 – 煎炸熊の記事本

容易混淆的誤區：網址中間或結尾帶 *

很多人會把 Nginx 的 location 當成一般的檔案搜尋（像 Windows 搜尋 *.txt 那樣用通配符），以為可以這樣寫：
❌ location /api/*/user （想代表中間任意字元）
❌ location /images/* （想代表路徑下的所有檔案）

:::warning
⚠️ 注意：在 Nginx 的普通前綴匹配中，星號 * 沒有任何特殊功能，它會被當成一個「真正的星號字元」！

:::

location 預設路徑

location /：比對所有以 / 開頭的請求。由於所有路徑都以 / 開頭，當找不到更精確的比對時，它會作為「預設路徑」。

1
2
3

location / {

}

加碼：Azure API Gateway 規則

PathPattern 重點整理

簡短說明

PathPattern 是一組以 / 開頭的路徑比對字串，可使用 * 作為萬用字元來匹配多種路徑。查詢字串（? 之後）與片段（# 之後）不會包含在比對範圍中，且路徑比對不分大小寫。 目前頁面 目前頁面

支援的範例與限制（快速表格）

參考: Azure Application Gateway URL-based content routing overview | Microsoft Learn