在 linux 中实现前后端分离项目的路由兼容，核心做法是在 nginx 配置中使用 try_files 指令将前端请求优先匹配静态资源，若未找到则回退到 /index.html。这样当用户刷新页面或分享深层链接时，nginx 不会返回 404，而是由前端路由接管处理。具体操作是定位到 location / 块，设置 try_files $uri $uri/ /index.html;，确保所有非文件请求都指向入口文件。
Nginx 如何处理前端路由的 404 问题
该问题的直接原因是浏览器刷新时向服务器请求了如 /user/profile 这样的路径，而服务器上并不存在对应的物理文件或目录，导致 Nginx 默认返回 404 错误。解决此问题的关键在于让 Nginx 在找不到对应资源时，不再报错，而是返回前端应用的入口文件 index.html。通过配置 try_files，我们可以定义一个查找顺序：先查文件，再查目录，最后 fallback 到首页。这样无论用户访问哪个前端路由，只要不是真实的静态资源，Nginx 都会把控制权交给前端 JavaScript，由前端路由器根据 URL 渲染正确的组件。
server {
listen 80;
server_name example.com;
# 前端静态资源目录
root /usr/share/nginx/html;
index index.html;
location / {
# 核心配置：尝试匹配 URI -> 目录 -> 回退到 index.html
try_files $uri $uri/ /index.html;
}
# 后端 API 代理配置
location /api/ {
proxy_pass http://backend_server:3000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
上述配置中，root 指定了静态文件的根目录。location / 块中的 try_files 指令是关键：$uri 检查是否存在同名文件（如 .js, .css），$uri/ 检查是否存在同名目录，如果两者都不存在，则内部重定向到 /index.html。同时，location /api/ 块负责将 API 请求转发给后端服务，避免与前端路由冲突。这种结构确保了静态资源正常加载，API 请求正确代理，且前端路由刷新不会报错。
如何区分静态资源请求与 API 请求
在前后端分离架构中，必须明确区分哪些请求应由 Nginx 直接提供静态文件，哪些应转发给后端 API。通常，前端构建后的静态资源（HTML, CSS, JS, Images）位于特定目录或直接放在根目录，而后端 API 请求往往带有特定的前缀，如 /api 或 /v1。通过在 Nginx 中为 API 路径单独定义 location 块，并使用 proxy_pass 指令，可以将这些请求透明地转发到后端服务。对于非 API 前缀的请求，则由通用的 location / 处理，执行 try_files 逻辑以支持前端路由。
# 假设后端运行在 localhost:3000
upstream backend {
server 127.0.0.1:3000;
}
server {
listen 80;
server_name example.com;
root /var/www/myapp/dist;
# 1. 精确匹配 API 前缀，优先于通用 location
location /api/ {
proxy_pass http://backend/;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 2. 处理静态资源和前端路由
location / {
try_files $uri $uri/ /index.html;
# 可选：缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}
}
在这个更完善的配置中，location /api/ 被放置在 location / 之前，因为 Nginx 会优先选择最长前缀匹配。这意味着任何以 /api/ 开头的请求都会被拦截并转发到 http://backend，而不会进入 try_files 逻辑。对于其他所有请求，包括 /, /about, /contact 等，都会进入第二个 location 块。其中嵌套的 location ~* \.(js|css|...) 用于对常见的静态资源进行缓存优化，提高加载速度。这种分层配置清晰地分离了关注点，既保证了 API 调用的正确性，又实现了前端路由的兼容性。
当后端 API 返回错误码时 Nginx 如何处理
当前端通过 API 获取数据时，后端可能会返回 4xx 或 5xx 错误码。如果直接使用默认的 Nginx 行为，用户可能会看到丑陋的默认错误页面。为了提升用户体验，可以配置 Nginx 将这些错误重定向到前端应用中的特定错误页面，例如 /error/404 或 /error/500。这需要利用 error_page 指令配合 internal 标记，或者直接在 proxy_intercept_errors 开启后，将错误响应重写为前端路由。由于前端路由依赖 index.html，我们需要确保错误页面的重定向不会破坏 try_files 的逻辑，通常做法是让后端在错误时返回特定状态码，Nginx 捕获后内部重定向到前端指定的错误路由，由前端展示友好的错误界面。
server {
listen 80;
server_name example.com;
root /var/www/myapp/dist;
# 开启错误拦截，允许 Nginx 处理后端返回的错误状态码
proxy_intercept_errors on;
# 定义错误页映射
error_page 404 /error/404;
error_page 500 502 503 504 /error/500;
# 标记为内部重定向，防止外部直接访问错误页源码
location = /error/404 {
internal;
try_files /error/404.html /index.html =404;
}
location = /error/500 {
internal;
try_files /error/500.html /index.html =500;
}
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://backend/;
# 确保后端错误能被 Nginx 捕获
proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;
}
}
在此配置中，proxy_intercept_errors on; 是关键，它告诉 Nginx 不要直接将后端返回的错误状态码和页面发给客户端，而是交由 Nginx 自己的错误处理机制处理。接着，error_page 指令将特定的 HTTP 状态码映射到内部的 URI，如 /error/404。这些内部 URI 所在的 location 块被标记为 internal，意味着它们不能通过浏览器地址栏直接访问，只能通过内部重定向触发。在这些内部 location 中，再次使用 try_files 来查找具体的 HTML 错误页面（如 /error/404.html），如果找不到，则 fallback 到 /index.html，由前端路由显示错误信息。这种方式既保持了 SPA 的单页体验，又提供了清晰的错误反馈。
