Nginx 本地 HTTPS 反向代理实战：前后端联调不再改端口

前后端本地联调时，经常会遇到几个小麻烦：前端跑在 localhost:5173，后端跑在 localhost:8080，接口地址要来回改；某些浏览器能力要求 HTTPS；Cookie 的 Secure、回调地址、OAuth 登录也希望本地环境更接近线上。

这时可以用 Nginx 在本机做一个 HTTPS 反向代理入口。浏览器只访问 https://local.dev.test，静态页面和接口请求都由 Nginx 分发到对应服务，联调体验会稳定很多。

摘要

本文用一个“前端页面 + 后端 API”的本地开发场景，演示如何生成自签证书、配置 Nginx HTTPS 入口、转发接口路径、保留真实请求头，并给出常见问题排查方法。配置保持最小可用，适合复制后按项目改造。

适合人群

适合正在做 Web 项目联调、需要本地 HTTPS、需要统一前后端入口的开发者。你需要本机已经安装 Nginx，并能编辑本机 hosts 文件和 Nginx 配置文件。

目录

1. 本地代理目标是什么
2. 准备 hosts 和证书目录
3. 生成自签证书
4. 编写 Nginx 反向代理配置
5. 启动检查和访问验证
6. 常见问题排查
7. 团队使用建议

一、本地代理目标是什么

假设你的项目有两个本地服务：

• 前端开发服务：http://127.0.0.1:5173
• 后端接口服务：http://127.0.0.1:8080

我们希望最终访问：

• https://local.dev.test/ 转到前端服务
• https://local.dev.test/api/ 转到后端服务

二、准备 hosts 和证书目录

先给本地域名加一条 hosts 记录。macOS 和 Linux 通常编辑 /etc/hosts，Windows 可以编辑系统 hosts 文件：

127.0.0.1 local.dev.test

再准备一个存放证书的目录。这里用项目内的 certs 举例：

mkdir -p certs

真实团队里可以把证书生成脚本放到工具目录，但不要把包含私钥的生产证书提交到仓库。本地自签证书只用于开发调试。

三、生成自签证书

用 OpenSSL 生成一组本地证书和私钥：

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout certs/local.dev.test.key \
  -out certs/local.dev.test.crt \
  -subj "/CN=local.dev.test"

浏览器第一次访问时可能会提示证书不受信任。开发阶段可以手动信任这张证书，或者使用团队统一的本地证书工具。重点是：本地 HTTPS 入口要固定，不要每个人都临时换域名和端口。

四、编写 Nginx 反向代理配置

下面是一份最小配置。不同安装方式的配置目录不一样，你可以放到 Nginx 的 conf.d 或本机单独 include 的目录里。

server {
    listen 443 ssl;
    server_name local.dev.test;

    ssl_certificate     /absolute/path/to/certs/local.dev.test.crt;
    ssl_certificate_key /absolute/path/to/certs/local.dev.test.key;

    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 https;
    }

    location / {
        proxy_pass http://127.0.0.1:5173/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

server {
    listen 80;
    server_name local.dev.test;
    return 301 https://$host$request_uri;
}

注意 location /api/ 里的 proxy_pass http://127.0.0.1:8080/; 末尾有斜杠。这会把 /api/users 转成后端的 /users。如果你的后端本身就以 /api 开头，需要按实际路径调整。

五、启动检查和访问验证

修改配置后，先检查语法：

nginx -t

检查通过后重载配置：

nginx -s reload

然后分别验证页面和接口：

curl -I https://local.dev.test/
curl -k https://local.dev.test/api/health

-k 只适合本地自签证书调试。线上环境不要用这种方式绕过证书校验。

六、常见问题排查

1. 浏览器打不开 local.dev.test

先确认 hosts 是否生效，再确认 Nginx 是否监听了 80 和 443 端口。可以用 ping local.dev.test 或 curl -I 做基础检查。

2. 页面打开了，接口 404

重点检查 location /api/ 和 proxy_pass 末尾斜杠。Nginx 的路径替换规则对斜杠很敏感，建议明确写出你希望后端收到的路径。

3. 后端拿到的协议还是 http

确认是否设置了 X-Forwarded-Proto https。一些框架会根据这个头判断原始访问协议，用于生成回调地址、Cookie 或跳转链接。

4. WebSocket 连接失败

如果前端开发服务需要 WebSocket 热更新，可以给对应 location 补充升级头：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

5. 证书信任反复弹窗

确认浏览器信任的是当前域名对应的证书。域名、证书 CN、访问地址不一致时，浏览器仍然会提示风险。

七、团队使用建议

• 把本地域名、端口、代理规则写进项目 README，避免每个人自己猜。
• 把 Nginx 配置做成模板，证书路径和端口通过注释说明。
• 前端请求尽量使用相对路径，例如 /api/users，减少环境切换成本。
• 自签证书只用于本地，测试和线上环境应使用正式证书和统一部署流程。
• 配置变更后固定执行 nginx -t，不要直接重载。

总结

Nginx 本地 HTTPS 反向代理的价值，是把复杂的本地端口和协议差异收敛到一个稳定入口。前端继续跑自己的开发服务，后端继续跑本地接口，浏览器只访问一个 HTTPS 域名。掌握 hosts、自签证书、proxy_pass 和代理头这几件事，就能把联调环境做得更接近线上，也更容易排查。

参考资料

本文参考 NGINX 官方关于反向代理、HTTPS server 配置和代理头转发的说明，示例为本地开发场景重新整理。