Nginx 中怎么使用 proxy_pass 实现前后端分离项目的反向代理-Nginx-PHP中文网

Nginx通过proxy_pass实现前后端分离反向代理，需配置静态资源服务（/var/www/frontend/dist）与/api/路径代理至后端（如http://127.0.0.1:3000），关键在于proxy_pass末尾斜杠控制路径重写、设置Host/X-Real-IP等请求头、支持history模式fallback，并注意开发跨域应由Nginx统一处理。

nginx 中怎么使用 proxy_pass 实现前后端分离项目的反向代理

在 Nginx 中用 proxy_pass 实现前后端分离项目的反向代理，核心是把前端静态资源请求（如 HTML、JS、CSS）直接由 Nginx 服务，而将 API 请求（如 /api/ 开头的路径）转发给后端服务（如 Node.js、Java、Python 后端）。关键在于路径重写、请求头设置和避免跨域问题。

配置静态资源服务 + API 代理

假设前端打包后放在 /var/www/frontend/dist，后端运行在 http://127.0.0.1:3000，API 接口统一以 /api/ 开头：

所有根路径（/）及子路径（如 /login、/assets/）优先匹配静态文件；找不到时返回 index.html（支持 Vue/React 的 history 模式）
/api/ 开头的请求全部代理到后端，且需去除前缀再转发（避免后端收到带 /api/ 的路径）
必须设置 Host、X-Real-IP 等请求头，让后端能正确识别客户端信息

示例配置片段：

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

# 前端路由 fallback（history 模式）
location / {
    try_files $uri $uri/ /index.html;
}

# API 反向代理
location /api/ {
    proxy_pass http://127.0.0.1:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

}

注意 proxy\_pass 路径结尾的斜杠

斜杠位置直接影响路径重写行为，这是最容易出错的地方：

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

proxy_pass http://127.0.0.1:3000/;（末尾有 /）→ 请求 /api/users 会转发为 http://127.0.0.1:3000/users（自动去掉 /api）
proxy_pass http://127.0.0.1:3000;（末尾无 /）→ 请求 /api/users 会转发为 http://127.0.0.1:3000/api/users（原样保留）

绝大多数前后端分离场景应使用带尾部斜杠的形式，确保后端无需处理 /api 前缀。

解决前端开发环境的跨域问题

开发时若前端跑在 http://localhost:5173、后端在 http://localhost:3000，浏览器会因同源策略拦截请求。此时可在开发服务器（如 Vite、Webpack Dev Server）中配代理，但上线部署时推荐统一由 Nginx 处理：

生产环境不依赖前端开发服务器的 proxy，所有请求走 Nginx，天然规避跨域
确保前端代码中 API 请求地址为相对路径（如 /api/login）或与部署域名一致的绝对路径（如 https://example.com/api/login），不要硬编码后端地址
如果后端需区分是否经代理访问，可通过 X-Forwarded-Proto 或自定义 header（如 X-From-Nginx: true）识别

可选：添加缓存与超时控制

提升稳定性与响应速度：

为 API 设置合理超时：proxy_connect_timeout 5s;、proxy_read_timeout 30s;、proxy_send_timeout 30s;
静态资源启用缓存：location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; }
对非敏感 API 响应做简单缓存（需后端配合设置 Cache-Control）：proxy_cache_valid 200 302 10m;

不复杂但容易忽略细节。配完记得 nginx -t 检查语法，再 nginx -s reload 生效。