本地开发时，置本前端跑在 3000 端口，地代后端 API 在 8080，理转浏览器一跨域就报错。置本改代码？地代加 CORS 头？太麻烦。最省事的理转办法是在 nginx 里配一条代理转发，让所有 /api 开头的置本请求直接打到后端，浏览器以为还在同源。地代

我自己的理转习惯是装个 nginx 在本地，监听 80 端口，置本前端请求统一走 http://localhost。地代下面这份配置我用了两年多，理转改改端口就能跑。置本

server {  listen 80; server_name localhost; location / {  root /Users/me/project/dist; index index.html; try_files $uri $uri/ /index.html; } location /api/ {  proxy_pass http://127.0.0.1:8080/; 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; } }

关键就两行。地代location /api/ 匹配所有以 /api/ 开头的理转请求，proxy_pass http://127.0.0.1:8080/ 把请求转发到本地 8080。注意 proxy_pass 末尾那个斜杠，有和没有差别很大。

斜杠的坑

写 proxy_pass http://127.0.0.1:8080/; 带斜杠，nginx 会把 location 匹配到的 /api/ 替换掉。请求 /api/user/list 转发过去变成 http://127.0.0.1:8080/user/list。

不带斜杠写 proxy_pass http://127.0.0.1:8080;，nginx 会把完整路径拼上去，变成 http://127.0.0.1:8080/api/user/list。

我踩过这个坑。后端接口没有 /api 前缀，配了不带斜杠的版本，结果所有请求 404，查了半小时才发现是斜杠的问题。现在养成了习惯，配完先 curl -v http://localhost/api/test 看一眼实际转发的路径。

WebSocket 怎么办

项目里用了 WebSocket 做实时通知，普通代理配置撑不住，连接会断。需要额外加几行：

location /ws/ {  proxy_pass http://127.0.0.1:8080/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600s; }

Upgrade 和 Connection 两个头是 WebSocket 握手的关键，不加的话 nginx 直接当普通 HTTP 请求处理，握手失败。proxy_read_timeout 默认 60 秒，长连接会被掐断，调到 3600 秒基本够用。

改完配置别急着重启

改完 nginx.conf 先跑 nginx -t 检查语法。我有次少写了个分号，直接 nginx -s reload，结果整个 nginx 挂了，前端页面都打不开。现在每次都先测试再 reload。

reload 是平滑重启，不会断开已有连接，比 restart 温和。macOS 上用 Homebrew 装的 nginx，配置文件在 /opt/homebrew/etc/nginx/nginx.conf，日志在 /opt/homebrew/var/log/nginx/。出问题先看 error.log，大部分情况是路径写错或者端口被占用。

一点个人经验

本地代理转发不用搞太复杂。有人喜欢用 webpack devServer 的 proxy，也能用，但 nginx 更贴近生产环境。本地调通了，上线换一下 proxy_pass 的地址就行，配置文件几乎不用动。

另外 proxy_set_header Host $host 这行建议保留。有些后端框架会根据 Host 头做路由或者签名校验，不传的话默认转发的是 127.0.0.1:8080，后端可能不认。我之前对接一个 Spring Boot 服务，就是因为没传 Host 头，接口一直返回 400。

配置这东西，写一次能用很久。花十分钟配好，省下的是后面无数次跨域调试的时间。