[!info] related notes

• 所属 MOC: Nginx MOC
• 对象页: Nginx
• 相关主题: Nginx 反向代理、负载均衡与网关入口

Nginx 中的 location、root、alias 与 proxy_pass

范围

• 这篇笔记专门处理 Nginx 配置里最常见的路径与匹配坑点。

为什么要放在一起理解

• 很多 404、静态资源错位、转发路径异常，本质都不是 Nginx “坏了”，而是匹配和路径规则没想清楚。

配置层级模型

典型结构：

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            root /var/www/html;
        }
    }
}

• main：全局配置，如 worker_processes、error_log。
• events：事件模型配置，如 worker_connections。
• http：HTTP 级通用配置，如 sendfile、gzip、upstream。
• server：虚拟主机。
• location：URI 路由规则。

location 匹配规则

常见写法：

location = /exact { }
location /prefix { }
location ^~ /static/ { }
location ~ \.php$ { }
location ~* \.jpg$ { }
location / { }

含义：

写法	含义
=	精确匹配
普通前缀	最长前缀匹配
^~	前缀命中后不再检查正则
~	区分大小写正则
~*	不区分大小写正则
/	兜底

可先记住这条：

精确匹配 > ^~ 前缀 > 正则（按顺序） > 普通最长前缀

root 和 alias 的区别

root

location /static/ {
    root /var/www;
}

请求：

/static/a.jpg

实际文件路径：

/var/www/static/a.jpg

alias

location /static/ {
    alias /data/assets/;
}

请求：

/static/a.jpg

实际文件路径：

/data/assets/a.jpg

记忆方式：

root：把完整 URI 追加到目录后面
alias：用指定目录替换匹配到的前缀

proxy_pass 的路径规则

不带 URI

location /api/ {
    proxy_pass http://backend;
}

请求：

/api/users

转发结果：

http://backend/api/users

带 URI

location /api/ {
    proxy_pass http://backend/;
}

请求：

/api/users

转发结果：

http://backend/users

再比如：

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

会转发到：

http://backend/v1/users

return、rewrite 与 try_files

return

适合简单返回或跳转：

location /health {
    return 200 "ok\n";
}

return 301 https://$host$request_uri;

rewrite

适合按规则改写 URI：

rewrite ^/old/(.*)$ /new/$1 permanent;

try_files

常用于 SPA 兜底：

location / {
    try_files $uri $uri/ /index.html;
}

即：

1. 先找文件
2. 再找目录
3. 都没有时回退到 /index.html

反向代理常见 Header

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

这些 Header 的作用是把原始 Host、客户端 IP 和原始协议传给后端，避免后端误以为所有请求都来自 Nginx 本机。