Nginx 中怎么配置 proxy_pass 实现单页应用服务的回退转发代理-Nginx-PHP中文网

Nginx代理SPA需配置回退机制解决前端路由404：用location ^~ /api/转发API请求，location ~* .(js|css|...)$提供静态资源，location /中try_files $uri $uri/ /index.html实现路由回退。

nginx 中怎么配置 proxy_pass 实现单页应用服务的回退转发代理

在 Nginx 中用 proxy_pass 代理单页应用（SPA）时，核心难点是解决前端路由（如 /about、/user/123）在刷新或直接访问时 404 的问题。这是因为 SPA 的路由由前端 JS 控制，而 Nginx 默认只按真实文件路径匹配，找不到对应静态资源或后端接口就会返回 404。正确做法是：将非 API 请求全部回退到 index.html，同时把 API 请求准确转发给后端服务。

区分 API 和前端路由请求

关键在于用 location 块精准识别请求类型：

以 /api/、/auth/ 等为前缀的请求 → 转发给后端服务
其他所有请求（包括根路径、/user、/app/settings 等）→ 返回 index.html，交由前端路由接管

配置示例（含静态资源和 API 代理）

假设前端构建产物放在 /var/www/my-spa，后端 API 地址是 http://127.0.0.1:3001：

server {
    listen 80;
    server_name example.com;
<pre class="brush:php;toolbar:false;">root /var/www/my-spa;
index index.html;

# 优先匹配 API 请求，转发到后端
location ^~ /api/ {
    proxy_pass http://127.0.0.1:3001/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# 匹配静态资源（js/css/img 等），正常提供
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 所有其他请求都 fallback 到 index.html
location / {
    try_files $uri $uri/ /index.html;
}

}

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

注意：try_files $uri $uri/ /index.html 是回退的关键——Nginx 先尝试找真实文件或目录，失败则返回 /index.html，且 URL 路径保持不变（前端 JS 可读取 location.pathname 进行路由匹配）。

常见陷阱与修正

proxy_pass 末尾斜杠影响路径重写：如果写成 proxy_pass http://127.0.0.1:3001;（无斜杠），Nginx 会把完整 URI（如 /api/users）原样转发；加斜杠（proxy_pass http://127.0.0.1:3001/;）则自动剥离 /api/ 前缀，转发 /users。通常推荐加斜杠，更符合 REST 语义
避免 location / {} 覆盖 API 规则：必须把 location ^~ /api/ 放在 location / 之前，否则会被通配规则提前捕获
history 模式需后端配合 CORS（若跨域）：若前端和 API 不同源，确保后端已设置 Access-Control-Allow-Origin 等响应头