Nginx Locationブロックのマッチングルール

locationディレクティブは、Nginx設定で最も重要かつ誤解されやすい概念の一つです。URIパスに基づいてNginxがリクエストをどのように処理するかを決定し、マッチングの優先順位を理解することが正しいルーティング動作に不可欠です。

Locationの種類と優先順位

Nginxは設定ファイルでの記述順序に関係なく、特定の優先順位でlocationブロックを評価します：

1. 完全一致（=）：最高優先度。URIに完全一致し、即座に検索を停止。
2. 優先プレフィックス（^~）：このプレフィックスがマッチすると、すべての正規表現評価をスキップ。
3. 正規表現（~ 大文字小文字区別、~* 大文字小文字無視）：ファイル内の記述順で評価。
4. プレフィックスマッチ（修飾子なし）：最長一致のプレフィックスが選ばれるが、正規表現マッチに上書きされる可能性あり。

location = /exact { }          # /exact のみにマッチ
location ^~ /images/ { }       # プレフィックスマッチ、正規表現をスキップ
location ~ \.php$ { }          # 大文字小文字区別の正規表現
location ~* \.(jpg|png)$ { }   # 大文字小文字無視の正規表現
location /documents/ { }       # 標準プレフィックス
location / { }                 # キャッチオールフォールバック

マッチングの仕組み（ステップバイステップ）

リクエストが到着すると、Nginxはまずすべてのプレフィックスlocation（通常と優先の両方）をチェックし、最長一致を記憶します。最長一致が ^~ 修飾子を使用している場合、正規表現評価は完全にスキップされます。そうでなければ、設定ファイルの記述順で正規表現locationをチェックします。正規表現がマッチすれば、記憶されたプレフィックスマッチより優先されます。正規表現がマッチしなければ、最長プレフィックスマッチが使用されます。

一般的な設定パターン

静的ファイルを直接配信し、その他はすべてプロキシ：

location ~* \.(css|js|jpg|png|gif|ico|svg|woff2)$ {
    root /var/www/static;
    expires 30d;
}

location / {
    proxy_pass http://backend;
}

別々のバックエンドによるAPIバージョニング：

location /api/v1/ {
    proxy_pass http://api_v1_backend;
}

location /api/v2/ {
    proxy_pass http://api_v2_backend;
}

ネストされたLocation

Locationは入れ子にできます。内部locationは外部locationのディレクティブを継承しますが、明示的にオーバーライドした場合は除きます：

location /app/ {
    proxy_pass http://backend;

    location /app/static/ {
        alias /var/www/static/;
    }
}

Locationマッチングのデバッグ

特定のリクエストをどのlocationブロックが処理しているか確認するには、各locationブロックにカスタムレスポンスヘッダーを追加します：

location / {
    add_header X-Debug-Location "root-catchall" always;
}

curl -I でレスポンスヘッダーを確認し、各リクエストパスに対して正しいブロックがマッチしていることを検証します。