排查 nginx proxy_pass 代理后静态资源 404,核心在于检查请求 uri 在 nginx 内部的重写与传递逻辑。通常是因为 location 块中的正则表达式捕获组未正确传递给后端,或者静态文件路径配置与实际磁盘路径不匹配。通过对比 nginx 访问日志中的原始请求 uri 和后端应用接收到的 uri,可以快速定位是 nginx 路由错误还是后端服务缺失该资源。

如何确认 Nginx 实际转发给后端的 URI 是什么
要确认 Nginx 实际转发给后端的 URI,最直接的方法是开启 Nginx 的调试日志或查看后端应用的访问日志。Nginx 默认不会记录它修改后的 URI,只记录客户端请求的原始 URI。因此,需要检查 Nginx 配置中 access_log 的格式,或者在后端应用中打印接收到的 REQUEST_URI。如果 Nginx 配置了 rewrite 或使用了带变量的 proxy_pass,URI 可能会发生变化。例如,使用 location /api/ { proxy_pass http://backend; } 时,请求 /api/test 会被转发为 /test;而使用 location /api/ { proxy_pass http://backend/; } 时,请求 /api/test 会被转发为 /test(注意尾部斜杠的影响)。若使用正则表达式 location ~ ^/api/(.*)$ { proxy_pass http://backend/$1; },则 $1 的值决定了最终路径。通过比对前后端日志,可以明确 URI 是否被意外截断或拼接错误。

server {
listen 80;
server_name example.com;
# 开启详细日志以便排查
access_log /var/log/nginx/access.log combined;
location /static/ {
alias /usr/share/nginx/html/static/;
try_files $uri $uri/ =404;
}
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
为什么静态资源路径在代理后无法找到
静态资源在代理后出现 404,往往是因为 alias 与 root 的使用混淆,或者 try_files 的路径解析失败。当使用 location /static/ 配合 alias /path/to/static; 时,请求 /static/file.js 会映射到 /path/to/static/file.js。但如果误用 root,则会映射到 /path/to/static/static/file.js,导致文件找不到。此外,如果静态资源由后端生成并通过 proxy_pass 返回,但前端请求的是直接路径而非 API 接口,Nginx 可能尝试从本地文件系统查找该文件,若不存在则返回 404。此时应确保静态资源请求由 Nginx 直接处理,或通过正确的 proxy_pass 规则转发至后端。检查文件权限、SELinux 上下文以及磁盘空间也是必要的步骤。

# 假设后端应用结构如下:
# /app/static/css/style.css
# /app/static/js/app.js
# Nginx 配置示例:正确区分 root 和 alias
location /assets/ {
# 使用 root 时,路径拼接为 /var/www/html/assets/ + $uri
root /var/www/html;
# 请求 /assets/css/style.css -> /var/www/html/assets/css/style.css
}
location /files/ {
# 使用 alias 时,路径替换为 /data/files/ + $uri
alias /data/files/;
# 请求 /files/doc.pdf -> /data/files/doc.pdf
# 注意:alias 末尾必须有斜杠
}
基于 proxy_pass 中尾部斜杠对 URI 重写的具体影响
在 proxy_pass 指令中,URL 是否包含尾部斜杠会显著改变转发行为。如果 proxy_pass 后面没有尾部斜杠,Nginx 会将完整的 location 匹配部分连同剩余 URI 一起发送给后端。例如,配置 location /api/ { proxy_pass http://backend; },请求 /api/v1/users 将被转发为 /api/v1/users。相反,如果 proxy_pass 包含尾部斜杠,如 proxy_pass http://backend/;,Nginx 会用 proxy_pass 的 URL 替换 location 的匹配部分,即 /api/ 被替换为 /,请求 /api/v1/users 将被转发为 /v1/users。这种差异会导致后端应用因路径不匹配而返回 404。开发者应根据后端框架的路由设计选择合适的配置方式,并在测试环境中验证 URI 转换结果。


















