Nginx 配置静态资源时 Root 与 Alias 如何选择

选 root 还是 alias，关键看 URL 路径和磁盘目录结构是否“对齐”：对齐用 root（全量拼接，保留 location 前缀），不对齐用 alias（前缀替换，末尾必须带/）；root 适合整站部署或路径结构一致，alias 适用于子应用挂载或无关目录映射。

选 root 还是 alias，关键看 URL 路径和磁盘目录结构是否“对齐”。对齐就用 root，不对齐、需要去掉前缀再映射就用 alias。

用 root 的典型场景

root 适合 URL 路径天然对应磁盘子目录层级的情况。Nginx 会把整个请求 URI（含 location 前缀）直接拼到 root 路径后面。

1. 整站部署：比如 Vue/React 构建产物放在 /var/www/dist，配置 location / { root /var/www/dist; } → 请求 /js/app.js 对应 /var/www/dist/js/app.js
2. 静态资源统一归口：所有图片都在 /data/www/images/，而 URL 是 /images/logo.png，那就配 location /images/ { root /data/www; } → 实际找 /data/www/images/logo.png
3. root 值末尾加不加 / 都行，Nginx 会自动处理，但统一写成 /var/www/dist/ 更清晰

用 alias 的典型场景

alias 本质是“路径替换”：location 匹配的部分被完全抹掉，只把剩余 URI 拼到 alias 目录后。它不依赖磁盘上存在对应前缀目录。

1. 子应用挂载：Vue 子应用构建在 /opt/admin-dist，但要通过 /admin/ 访问 → 配 location /admin/ { alias /opt/admin-dist/; } → /admin/js/app.js 查 /opt/admin-dist/js/app.js
2. 资源整合映射：Swagger UI 文件在 /opt/swagger-ui/，想挂到 /api/docs/ → location /api/docs/ { alias /opt/swagger-ui/; }
3. alias 值末尾必须带 /，否则 alias /opt/swagger-ui 会导致 /api/docs/index.html 错拼成 /opt/swagger-uiindex.html
4. location 也建议以 / 结尾（如 /admin/），避免正则匹配歧义或路径截断

常见错误与避坑点

这些细节一错，404 就跟着来：

1. 同一 location 块里不能同时写 root 和 alias，Nginx 启动直接报错
2. 用 alias 时，try_files $uri $uri/ /admin/index.html 中的 fallback 路径必须带 location 前缀（如 /admin/index.html），否则 Vue Router history 模式无法回退
3. 正则 location（如 location ~ .js$）中慎用 alias；虽然新版 Nginx 支持命名捕获，但兼容性和可维护性不如普通 location，生产环境尽量避开
4. 不要用 alias 配 location /，这种全量匹配更适合 root

一句话决策流程

看到一个 URL，比如 /static/css/main.css，先问自己：

→ 磁盘上有没有 /var/www/static/css/main.css 这个完整路径？有 → 用 root。

→ 实际文件在 /data/assets/css/main.css，只想把 /static/ 这层前缀去掉？→ 用 alias。