Nginx部署Vue/React项目时无法直接访问页面其他路径的问题及解决方案

在现代前端开发中，Vue和React都是非常流行的前端应用框架，它们支持构建单页应用（SPA）。然而，在将 Vue/React项目部署到生产环境时，开发者经常会遇到一个问题：当用户直接访问非根路径（如 /admin/login 或 /user/profile）时，Nginx 返回 404 错误页面。本文将深入探讨这一问题的原因，并提供完整的解决方案。

1. 问题现象

当你使用 vue-cli 构建并打包一个 Vue 项目后（或者使用React构建项目），将其部署到 Nginx 服务器上。如果用户通过浏览器地址栏直接输入类似 https://xs.zhaoshang.cc/about 的 URL，会发现页面无法加载，Nginx 返回 404 错误。

2. 问题原因

这个问题的根本原因在于 Vue Router 使用了 HTML5 History 模式 , 而React Router采用了 BrowserRouter（History模式）。

在 SPA 应用中，所有的页面跳转都是由前端 JavaScript 控制的，而不是通过传统的服务器端路由。
当你启用 history 模式（即不带 # 的 URL），Vue Router/React Router会利用浏览器的 History API 来管理路由。
然而，Nginx 默认的行为是：当接收到一个请求（例如 /admin/login），它会在服务器文件系统中查找对应的文件（如 /admin/login.html 或 /admin/login/index.html）。
如果找不到该文件，Nginx 就会返回 404 错误。

因此，我们需要告诉 Nginx：对于所有未匹配到静态资源的请求，都应该返回 index.html 文件，让前端 Vue/React应用来处理这些路由。

3. 解决方案

只需在 Nginx 的配置文件中添加以下关键配置：

nginx 复制代码

location / {
    try_files $uri $uri/ /index.html;
}

(1). 配置说明

try_files 指令会按顺序尝试以下路径：
1. $uri：查找与请求 URI 完全匹配的静态文件（如 /css/app.css）
2. $uri/：尝试将 URI 作为目录，并查找其下的 index.html
3. /index.html：如果以上都失败，则返回根目录下的 index.html

(2). 路径匹配机制

location /表示匹配所有根路径下的请求。当用户访问任意URL时（如/admin或/talent），Nginx会按照try_files指令的顺序尝试查找对应资源。

(3). 单页SPA路由处理

对于Vue或React构建的单页SPA应用：

直接访问静态资源（如CSS/JS）时，前两个参数会匹配到实际文件;
访问前端路由路径时，因物理文件不存在，最终会回退(fallback)到index.html;
前端框架（如React/Vue）接管路由，根据URL渲染对应组件.

这样，无论用户访问哪个路径，只要不是真实的静态资源，最终都会加载 index.html，然后由 Vue Router 根据当前 URL 渲染对应的组件。

4. 实际部署示例

下面是一个完整的 Nginx 配置示例：

nginx 复制代码

server {
    listen 80;
    server_name xs.zhaoshang.cc;
    root /var/www/operation/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
        expires -1;  # 禁用缓存，确保每次都能获取最新的 index.html
    }

    # 静态资源可以设置长期缓存
    location /static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

5. 扩展知识点

(1). 如何测试配置是否生效？

修改 Nginx 配置后，先运行 nginx -t 测试语法是否正确
然后执行 nginx -s reload 重载配置
直接在浏览器中访问非根路径（如 /login），看是否能正常显示页面

(2). 其他注意事项

如果你的 Vue 项目使用了 hash 模式（URL 中包含 #），则不会出现此问题，因为所有请求实际上都是对根路径的请求。
对于 API 请求，通常应该配置反向代理，避免与前端路由冲突：
nginx 复制代码
```
location /api/ {
    proxy_pass http://backend-server;
}
```

(3). 安全建议

不要将 try_files 的 fallback 设置为 =404，这会导致 SPA 路由失效
确保 index.html 文件具有正确的权限，Nginx 能够读取

6. 总结

Nginx 部署 Vue 项目时无法直接访问其他路径的问题，本质上是由于服务器端路由与前端路由的不匹配造成的。通过在 Nginx 配置中使用 try_files $uri $uri/ /index.html;，我们可以完美解决这个问题，确保 SPA 应用的所有路由都能正常工作。

这个配置不仅适用于 Vue 项目，同样适用于 React、Angular 等其他基于 History 模式的单页应用框架。掌握这个技巧，将帮助你在前端工程化和部署方面更加得心应手。