nginx location匹配按=、^~、普通前缀、正则四阶段筛选:=精确匹配立即终止;^~最长前缀命中即停,跳过正则;普通前缀仅在无=和^~时生效;正则按配置顺序首中即止。

理解 Nginx location 匹配优先级,关键不是死记顺序,而是看清它分阶段筛选的执行逻辑。配置出错(比如静态资源 404、API 被误代理、首页跳转失效)往往不是规则写错了,而是没搞清哪一条真正生效了。
精确匹配(=):一锤定音,不讲余地
只要请求 URI 和 location = /path 完全一致(忽略 ? 后面的 query string,不接受多一个字符、少一个斜杠或大小写差异),就立刻终止匹配,后续所有 location 都不检查。
-
location = /health只匹配/health,不匹配/health/、/healthz或/HEALTH - 哪怕它写在配置文件最底下,只要命中,就赢了——不用靠“写在前面”抢优先级
- 适合高频、短路径、无歧义的入口,例如:
location = /favicon.ico { return 204; }
前缀匹配中的 ^~:踩下急刹车,跳过正则
没命中 = 时,Nginx 会从所有前缀类 location(含 ^~ 和普通 /path)中,选出 URI 最长的那个。但若这个最长匹配是 ^~,就直接采用,不再检查任何正则(~ 或 ~*)。
-
location ^~ /api/匹配/api/v1/users,即使后面有location ~ \.json$,也不会执行 - 想确保静态资源不被正则劫持?统一用
^~:location ^~ /static/、location ^~ /assets/ - 别混用:
location ^~ /js/和location ~ \.js$同时存在,后者永远不生效
正则匹配(~ 和 ~*):按序扫描,首中即止
只有当最长前缀匹配是普通前缀(无 ^~),且它没做拦截(比如没配 proxy_pass 或 return),Nginx 才从上到下逐条试 ~ 和 ~*,遇到第一个能匹配的就停。
- 顺序很重要:
location ~ \.(jpg|png)$写在location ~ \.jpg$前面,后者永远不会触发 - 边界要明确:用
~ \.php$,别写~ php$,否则会错误匹配/backup.php.bak - 大小写注意:
~ \.JPG$不匹配.jpg;需要兼容就用~* \.jpg$
普通前缀(无修饰符):最长匹配,但最易被覆盖
location /admin 这类属于普通前缀,在四层里优先级最低。它只在没有 =、没有更优 ^~、也没被正则截胡时才生效。
- 它实际匹配所有以
/admin开头的路径,包括/admin/login、/admin-api - 如果还写了
location ~ \.php$,那么/admin/index.php就会进正则块——可能绕过你为/admin设的 auth 或proxy_pass - 想精准控制?把权限或代理逻辑提前:
location ^~ /admin/拦住目录,再单独配location = /admin处理首页











