Nginx静态资源配置指南：root指令与项目路径对齐-Nginx-PHP中文网

root指令是url路径拼接而非映射，其值须与前端构建输出路径、请求url三者对齐；例如location /assets/ { root /var/www/myapp; }时，请求/assets/js/app.js会查找/var/www/myapp/assets/js/app.js。

nginx静态资源配置指南：root指令与项目路径对齐

配置 Nginx 提供静态资源时，root 指令的值必须与前端构建输出路径、URL 请求路径三者对齐，否则会出现 404 或资源加载失败。核心不是“放对文件”，而是“让 Nginx 能按请求 URL 正确拼出物理路径”。

root 不是“把这里设成网站根目录”，而是“把请求 URI 的完整路径追加到这个路径后面”。例如：

配置：
location /assets/ {
root /var/www/myapp;
}

当浏览器请求 /assets/js/app.js，Nginx 实际查找的文件是：
/var/www/myapp/assets/js/app.js

注意：URI 中的 /assets/ 会被完整保留并拼在 root 后面 —— 这就是“拼接”，不是“替换”或“截断”。

以下情况极易导致 404，本质都是 root 值与前端实际部署结构不一致：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

前端构建输出到 dist/，但 root 指向项目根目录：
错误写法：root /var/www/myproject;（而实际 HTML/JS 在 /var/www/myproject/dist/）
→ 应改为：root /var/www/myproject/dist;
访问根路径 /，但前端是单页应用（SPA），index.html 在子目录：
若所有资源放在 /var/www/spa/，且 index.html 就在此目录下，则应：
location / { root /var/www/spa; index index.html; }
不要写成 root /var/www/spa/; location / { ... }（末尾斜杠不影响，但语义易混淆）
有子路径部署（如部署在 /admin/ 下）：
前端构建时需配置 publicPath: "/admin/"，Nginx 则用：
location /admin/ { root /var/www/admin-app; }
此时请求 /admin/css/main.css → 查找 /var/www/admin-app/admin/css/main.css（再次强调：/admin/ 会拼上）

如果不想让 URI 前缀重复出现在文件路径中（比如希望 /static/ 直接指向 /var/www/static/，而不是拼出 /var/www/static/static/），用 alias：

location /static/ {
alias /var/www/shared-assets/;
}

此时请求 /static/logo.png → 查找 /var/www/shared-assets/logo.png（/static/ 被完全替换，不参与拼接）。

⚠️ 注意：alias 后路径末尾必须有斜杠（除非指向具体文件），且 location 的 URI 必须以 / 结尾才匹配成功。

配置后别急着 reload，先做三件事：

用 nginx -t 检查语法；
确认文件权限：Nginx 工作进程（通常是 www-data 或 nginx 用户）能读取目标目录及文件；
开启 error_log debug 级别（临时），或用 curl -I http://localhost/path/to/file 看返回状态和响应头，结合 Nginx 日志中的 open() "/path/..." failed 行定位真实查找路径。