在 nginx 中处理前后端分离项目的静态托管，核心做法是配置 `root` 指令指向前端构建后的文件目录（如 `dist/`），并通过 `try_files` 指令配合正则表达式拦截所有非静态文件的请求，将其重定向到入口文件 `index.html`。这样既能让浏览器直接获取 js、css 等静态资源，又能确保 vue router 或 react router 等前端路由在刷新页面时不会返回 404 错误。
Nginx 如何区分并正确返回静态资源
当用户访问项目域名时，Nginx 会根据请求的 URI 路径查找对应的物理文件。如果请求的是 `/app.js` 或 `/style.css`，Nginx 会直接在配置的 `root` 目录下寻找这些文件并返回内容；如果请求的是后端接口地址，则通过反向代理转发。这种机制依赖于文件系统的路径映射，确保静态资源能被高效读取。
server {
listen 80;
server_name example.com;
# 定义根目录，指向前端打包后的文件夹
root /var/www/my-app/dist;
index index.html;
# 静态资源缓存优化
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# 后端 API 代理
location /api/ {
proxy_pass http://backend_server:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
上述配置中，`root` 指定了 `/var/www/my-app/dist` 为服务器根目录。当请求 `/app.js` 时，Nginx 实际去磁盘读取 `/var/www/my-app/dist/app.js`。对于图片、脚本和样式表，我们单独设置了较长的缓存时间，因为这类文件通常带有哈希值，内容变更时文件名也会改变，适合长期缓存。API 请求则被转发到后端的 3000 端口，实现了动静分离。
前端路由刷新 404 问题的解决方案
在单页应用（SPA）中，前端路由通常使用 History 模式，URL 看起来像真实的页面路径（如 `/user/profile`）。但服务器上并不存在这个物理文件或文件夹。如果不做特殊处理，用户刷新页面或分享链接时，Nginx 会尝试寻找 `/user/profile` 目录下的 `index.html`，找不到则返回 404。解决这个问题的关键在于利用 `try_files` 指令进行回退处理。
location / {
try_files $uri $uri/ /index.html;
}
这段配置的含义是：首先尝试匹配请求的 URI `$uri`（例如 `/user/profile`），如果文件不存在，再尝试将其视为目录 `$uri/`，如果还不是目录，最后 fallback 到 `/index.html`。这样，无论用户访问哪个前端路由路径，Nginx 都会返回同一个 `index.html`，由前端 JavaScript 接管路由解析，从而避免 404 错误。这是前后端分离部署中最常见的配置片段。
当 try_files 未生效导致 404 时的排查
如果在配置了 `try_files $uri $uri/ /index.html;` 后仍然出现 404 错误，通常是因为 `root` 路径设置错误或权限问题。例如，如果 `root` 指向了错误的上级目录，或者 Nginx 进程没有读取 `dist` 目录的权限，Nginx 可能无法找到 `index.html` 文件本身，从而导致静默失败或返回 403/404。此外，如果使用了 `alias` 而非 `root`，`try_files` 的行为会有所不同，需要特别注意路径拼接逻辑。
# 错误示例：使用 alias 时 try_files 可能失效
location /app/ {
alias /var/www/my-app/dist/;
# 这里 try_files 可能会因为路径转换问题找不到 index.html
try_files $uri $uri/ /app/index.html;
}
在使用 `alias` 时，URI 中的 `/app/` 会被替换为 `/var/www/my-app/dist/`。因此，当请求 `/app/user` 时，Nginx 内部路径变为 `/var/www/my-app/dist/user`。此时 `try_files` 应该指向 `/app/index.html` 而不是 `/index.html`，因为 `/index.html` 会被解析为 `/var/www/my-app/dist/index.html`，而 `/app/index.html` 会被解析为 `/var/www/my-app/dist/app/index.html`（这通常是错的）。最稳妥的方式是使用 `root` 配合 `location /`，或者在 `alias` 场景下仔细调整 `try_files` 的 fallback 路径。建议优先使用 `root` 指令简化配置逻辑。
