nginx proxy_pass 实现前后端分离接口转发需正确匹配路径、处理末尾斜杠、透传请求头并配置超时与前端路由回退；location /api/ 配 proxy_pass http://backend/（带斜杠）可去除前缀，配合 try_files $uri $uri/ /index.html 解决 history 模式 404。
Nginx 的 proxy_pass 是实现前后端分离项目中接口转发的核心配置，关键在于正确匹配请求路径、改写 URI、透传必要头信息，并避免跨域问题。下面从常用场景出发，讲清楚怎么配才不踩坑。
明确区分静态资源和 API 请求
前端通常打包成静态文件（如 /index.html），后端提供接口（如 /api/users）。Nginx 需把带 /api/ 前缀的请求转发给后端服务，其余请求直接返回前端资源。
- 前端资源走
root或alias，比如root /var/www/dist; - API 请求用
location /api/ { proxy_pass http://backend; }，注意末尾斜杠的作用
理解 proxy_pass 末尾斜杠的含义
这是最容易出错的地方：
-
proxy_pass http://127.0.0.1:3000/;（带斜杠）：会删除匹配的 location 前缀，再拼接。例如location /api/匹配/api/users，实际转发为http://127.0.0.1:3000/users -
proxy_pass http://127.0.0.1:3000;（不带斜杠）：会保留完整原始 URI，转发为http://127.0.0.1:3000/api/users
多数后端服务期望接收不带 /api 前缀的路径，所以推荐第一种写法，配合 location /api/ 使用。
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
补充必要的代理头和超时设置
只写 proxy_pass 不够，后端可能拿不到真实 IP、协议或 Host，导致重定向异常或鉴权失败。
- 加
proxy_set_header Host $host;保证后端看到原始 Host - 加
proxy_set_header X-Real-IP $remote_addr;和X-Forwarded-For传递客户端 IP - 加
proxy_set_header X-Forwarded-Proto $scheme;让后端知道是 HTTP 还是 HTTPS - 设置
proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout（如 60s），避免长接口被中断
处理前端路由（History 模式）和 404
Vue Router 或 React Router 的 History 模式下，刷新 /user/123 会 404，因为 Nginx 找不到对应文件。
- 在
location /块中加try_files $uri $uri/ /index.html; - 确保该配置放在
location /api/等 API 规则之后（Nginx 优先匹配最长前缀），避免把 API 请求也 fallback 到index.html
配完记得 nginx -t 检查语法，再 nginx -s reload 生效。只要路径匹配逻辑清晰、斜杠用对、头信息传全，接口转发就基本稳了。
