调试Nginx alias路径映射的核心是通过error_log查看真实打开路径，结合$request_filename日志验证拼接结果，并用测试文件反向确认映射有效性，同时严格检查权限、斜杠一致性及绝对路径真实性。
调试 Nginx alias 路径映射，核心是确认 Nginx 实际访问的文件路径是否与预期一致。不靠猜，靠日志和验证。
看 error_log 显示真实打开路径
这是最直接、最可靠的方式。Nginx 在找不到文件或权限不足时，会在 error log 中明确写出它尝试打开的绝对路径。
- 在 server 或 http 块中开启 debug 级别日志：error_log /var/log/nginx/error.log debug;
- 触发一次请求（比如 curl http://localhost/static/logo.png）
- 查看日志中类似这样的行：*1234 open() "/var/www/assets/logo.png" failed (2: No such file or directory)
- 这条信息告诉你：Nginx 确实按 alias 规则拼出了 /var/www/assets/logo.png，但该路径不存在——问题就出在路径拼接逻辑或文件位置上
用 $request_filename 验证拼接结果
这个变量是 Nginx 内部已根据 alias（或 root）计算出的最终文件路径，比手动推算更准确，适合写进 access_log 辅助观察。
- 定义一个带变量的日志格式：log_format debug '$remote_addr - "$request" → $request_filename';
- 在 location 块中启用：access_log /var/log/nginx/alias_debug.log debug;
- 请求后查看日志，就能看到每次请求对应的真实磁盘路径，例如：127.0.0.1 - "GET /static/js/app.js HTTP/1.1" → /project/dist/js/app.js
临时放测试文件快速验证
避免反复改配置重启，用“存在性”反向验证映射是否生效。
- 在你期望 alias 指向的目录里，手动创建一个简单文件，比如 /project/dist/test.ok
- 访问对应 URL：curl -I http://yoursite/static/test.ok
- 如果返回 200，说明路径映射正确；如果 404，说明 alias 拼出的路径不对；如果 403，大概率是权限或目录执行位（x）缺失
检查权限和路径结构是否匹配
很多“404”其实是“403”伪装的，尤其在 Docker 或挂载目录场景下。
- 确认 alias 后的路径是容器内或服务器上真实存在的绝对路径（不是相对路径，也不含未解码的 %xx）
- 确保 Nginx 工作进程用户（如 www-data、nginx 或 nobody）对目标目录有 r-x 权限（目录需 x 才能进入）
- 检查 location 和 alias 结尾斜杠是否一致：location /static/ { alias /project/dist/; } —— 两者都带 / 是安全组合
