最近帮团队搭本地联调环境前后端同事差点吵起来。前端说接口全是 http 请求被浏览器拦得死死的后端说证书配置太麻烦根本不想碰。最后我直接用 Nginx 在本地做了一个 http 转 https 的统一入口前后花了不到十分钟两边都消停了。所谓 http 转 https本质上是让 Nginx 充当一个带 SSL 终结能力的反向代理客户端通过 https 访问 NginxNginx 解密后再把请求转发给背后跑着 http 服务的本地应用。后端代码一行不用改就完成了从明文到加密的切换。这篇文章我会把整套方案从头到尾过一遍为什么本地也需要 HTTPS、自签名证书怎么生成、Nginx 配置怎么写、多项目怎么分流、以及我这些年踩过的一堆坑。适合做 Web 开发、前后端联调、以及有本地环境维护需求的运维同学参考看完就能直接照抄。1. 方案思路为什么本地也得折腾 HTTPS1.1 本地开发逃不掉的三个场景先说说我为什么要折腾这件事。日常开发里你至少会遇到下面三种情况跑都跑不掉前端页面已经部署在 https 域名下浏览器会直接拦截从 https 页面发往 http 接口的请求这就是混合内容Mixed Content问题。打开 Chrome 控制台满屏都是 This request has been blocked。微信、小程序、某些 App 的 WebView 对 http 限制更严格不仅拦截有的直接白屏。想本地调试这类环境不搞 https 根本进不去。Cookie 的 Secure 属性。线上环境签发 Cookie 时带上了 Secure 标记本地 http 环境无法回传这种 Cookie登录态在本地直接失效。联调登录功能时最容易踩这个。这些问题的根源就是本地环境和线上环境的“协议不对称”。与其在代码里到处打补丁不如在入口处统一解决——这就是 Nginx 做 http 转 https 的价值把所有本地 http 服务统一收口到一个 https 入口后面前端、后端、联调脚本全部走同一条加密通道。1.2 HTTP 和 HTTPS 的真实区别很多同学对这两个协议的理解停留在“HTTPS 更安全”一句话上但做配置的时候你得知道它到底改了什么。HTTP 是明文协议客户端和服务器之间的请求、响应、Cookie、Token全部裸奔在网络里任何能截获流量的人都能直接看到内容。HTTPS 并不是一个全新协议它是 HTTP 和 TLS/SSL 的组合核心逻辑是先通过 TLS 握手完成身份验证和密钥协商之后所有 HTTP 数据都用对称加密传输。换句话说HTTPS 多出来的工作量全部集中在握手阶段。握手阶段有两件重要的事第一服务器向客户端出示数字证书证明“我是谁”第二双方协商出会话密钥后续数据全部走加密通道。这也解释了为什么本地开发要用自签名证书。证书的作用是身份证明自签名证书只是没有经过 CA证书颁发机构背书它在加密能力上和正规证书没有任何区别。本地调试完全够用唯一的问题是浏览器默认不认它手动信任一下就好。1.3 为什么选 Nginx 而不是其他工具本地实现 https 的方案其实不少我简单列一下对比方案适用场景缺点后端框架自带 TLS单个服务每个服务都要单独配改动侵入业务代码Node.js https 模块Node 服务只对 Node 生态有效Java/Go 等不适用Nginx 统一入口多服务、多项目需要懂一点 Nginx 配置但学习成本很低我推荐 Nginx 的核心原因有三个。一是收口本地可能有前端 dev server、后端 API、文件服务、Mock 服务等多个进程同时跑Nginx 一次性全部接管按域名或路径分流二是改动小后端服务完全不用感知 HTTPS代码一行不用动三是一致性线上生产环境通常也是 Nginx 做 SSL 终结本地和线上配置逻辑一致调试环境就相当于生产环境的缩小版排查思路可以无缝复用。2. 准备工作安装 Nginx、生成自签名证书2.1 不同平台下 Nginx 的安装方式Nginx 的安装方式根据操作系统不同略有差别我把常用的列出来macOS直接用 Homebrew执行brew install nginx。装完配置文件在/usr/local/etc/nginx/nginx.confIntel 芯片或/opt/homebrew/etc/nginx/nginx.confApple Silicon。Ubuntu/Debiansudo apt update sudo apt install nginx。配置文件在/etc/nginx/nginx.conf站点配置习惯放在/etc/nginx/sites-available/和/etc/nginx/sites-enabled/。CentOS/RHELsudo yum install nginx或sudo dnf install nginx配置主文件路径同样是/etc/nginx/nginx.conf。Windows去官网下载稳定版 zip 包解压后直接运行nginx.exe。Windows 下配置语法和 Linux 完全一致但注意没有守护进程改配置用nginx -s reload生效。我自己的习惯是本地项目单独建一份配置文件目录不在主配置文件里直接改而是用include把项目配置引进去。这样不同项目之间互不污染删除某个项目时直接把对应配置移除就行非常干净。提示装完先跑nginx -t验证语法再执行nginx -s reload。很多初学者改完配置直接重启语法报错会导致整个 Nginx 起不来这是一条被反复验证的教训。2.2 用 OpenSSL 一键生成自签名证书Nginx 做 https必须要有证书和私钥。本地调试不需要去 CA 机构申请用 OpenSSL 生成自签名证书就行一条命令搞定openssl req -x509 -newkey rsa:2048 -nodes \ -keyout localhost.key \ -out localhost.crt \ -days 365 \ -subj /CNlocalhost逐个解释关键参数req -x509生成自签名证书而不是生成证书签发请求CSR。newkey rsa:2048同时生成新的 RSA 密钥对长度 2048 位。2048 是当前最低推荐标准千万别用 1024浏览器会直接嫌弃。-nodes私钥不加密。生产环境不建议这么干但本地调试图方便。-keyout/-out分别指定私钥和证书的输出路径。-days 365有效期 365 天。macOS 的 Chrome 对超过 398 天的证书会直接报错所以设 365 天最稳。-subj /CNlocalhost证书的 Common Name。如果只是单机本地访问写localhost就够如果要用自定义域名比如dev.example.com这里要写域名并且 Nginx 配置里的server_name要和它一致。如果你想用局域网 IP 在手机上调试或者一个证书要覆盖多个域名就需要加 SANSubject Alternative Name扩展openssl req -x509 -newkey rsa:2048 -nodes \ -keyout localhost.key \ -out localhost.crt \ -days 365 \ -subj /CNlocalhost \ -addext subjectAltNameDNS:localhost,DNS:dev.example.com,IP:127.0.0.1,IP:192.168.1.100SAN 里可以混写 DNS 和 IP浏览器校验证书时优先看 SAN。如果你的页面会通过局域网 IP 被手机访问务必把 IP 加进去不然手机端永远报证书错误而且这种报错在电脑上还复现不出来非常坑。2.3 把自签名证书装进系统信任区生成完证书后直接访问 https://localhost 会被浏览器拦一大屏。原因前面说过证书没有 CA 签名浏览器无法验证身份。解决方案是把它加入系统信任区。macOS双击localhost.crt在“钥匙串访问”里导入选择“系统”钥匙串把证书的信任级别改为“始终信任”。Windows双击 crt 文件选择“安装证书”存储位置选“本地计算机”然后放到“受信任的根证书颁发机构”目录下。Ubuntusudo cp localhost.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates。移动端通过邮件或网盘把 crt 传给手机安装。iOS 安装后还要去“设置 - 通用 - 关于本机 - 证书信任设置”里打开开关Android 不同版本入口略有差异但逻辑基本一致。注意自签名证书只适合开发环境。如果用在生产环境用户会看到“不安全”警告而且一旦站点启用了 HSTS 等严格安全策略浏览器会直接拒绝连接。生产环境请走 Lets Encrypt 或云服务商的证书申请流程。3. 核心配置Nginx 实现 HTTP 转 HTTPS3.1 最基础的 SSL 终结配置证书和私钥就绪后先写一个最小的反向代理配置。假设本地有一个服务跑在127.0.0.1:8080我们需要让 Nginx 监听 443 端口以 https 接收请求然后转发到 8080server { listen 443 ssl; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { 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; } }这套配置的核心逻辑就是“SSL 终结”客户端和 Nginx 之间是加密的 httpsNginx 和后端服务之间是普通 http。后端代码完全不用管 TLS 的事只管处理业务逻辑。几个协议头是必须的Host $host保留原始请求的域名否则后端拿到的是127.0.0.1生成链接、做路由判断时都会出错。X-Real-IP和X-Forwarded-For把客户端真实 IP 传给后端。不加的话后端看到的全是 Nginx 本机地址日志和鉴权都会出问题。X-Forwarded-Proto $scheme告诉后端“原始请求是 https”。后端生成重定向、拼接回调地址时都会判断这个头少了它很容易出现“回调地址变成了 http”的诡异问题。3.2 HTTP 强制跳转 HTTPS 的三种写法光有 443 监听还不够用户访问http://localhost:8080时仍然走的是明文。通常我们要把 80 端口的请求强制跳转到 https。最简单、最常用的写法server { listen 80; server_name localhost; return 301 https://$host$request_uri; }这里return 301返回一个永久重定向$host和$request_uri会拼出完整的 https 地址。比如用户访问http://localhost/login会被重定向到https://localhost/login。第二种写法是用rewriteserver { listen 80; server_name localhost; rewrite ^(.*)$ https://$host$1 permanent; }效果上和return 301类似但官方更推荐用return。因为它直接返回重定向响应不走正则匹配性能更好语义也更清晰。我的建议是直接用return 301没有特殊情况不需要考虑 rewrite。第三种是只跳转特定路径。比如你只想让/api走 https其他路径放行可以在 80 端口的 location 里单独处理server { listen 80; server_name localhost; location /api { return 301 https://$host$request_uri; } location / { proxy_pass http://127.0.0.1:8080; } }对于本地调试我一般直接用全量跳转。但要注意如果你的后端接口同时存在 http 和 https 两种调用方式全量跳转会导致每次 http 请求都增加一次网络往返。本地无所谓生产环境需要斟酌。3.3 单机多项目怎么分流本地最常见的情况是同时跑好几个项目一个前端 dev server、一个后端 API、一个管理后台、一个文件服务。Nginx 的强项在于可以用一个 443 端口接收所有请求然后按域名或按路径分流到不同端口。按域名分流的配置server { listen 443 ssl; server_name project-a.local; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; } } server { listen 443 ssl; server_name project-b.local; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { proxy_pass http://127.0.0.1:4000; proxy_set_header Host $host; } }使用域名分流时需要改 hosts 文件把project-a.local和project-b.local指向127.0.0.1。macOS/Linux 的 hosts 文件在/etc/hostsWindows 在C:\Windows\System32\drivers\etc\hosts。这里有个重点证书 SAN 里必须包含这些域名否则浏览器照样报证书错误。按路径分流的配置server { listen 443 ssl; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location /api/ { proxy_pass http://127.0.0.1:8080; } location /admin/ { proxy_pass http://127.0.0.1:9000; } location / { proxy_pass http://127.0.0.1:3000; } }按路径分流有个经典大坑proxy_pass后面有没有末尾斜杠行为完全不同。对比一下就明白了proxy_pass 写法请求 /api/user后端实际收到proxy_pass http://127.0.0.1:8080;/api/user/api/userproxy_pass http://127.0.0.1:8080/;/api/user/userproxy_pass http://127.0.0.1:8080/api/;/api/user/user也就是说proxy_pass末尾带斜杠Nginx 会把 location 匹配到的前缀剥掉再转发。这个细节经常导致接口 404排查半天最后发现是斜杠问题。我的建议是除了明确要做前缀剥离的场景一律不加末尾斜杠。3.4 进阶增强HTTP/2、WebSocket 与连接复用基础配置跑通之后有几个增强项值得加上能明显改善体验。HTTP/2 能显著提升页面加载速度尤其适合有大量并发请求的页面。老版本写法是在listen 443 ssl后面直接加http2参数server { listen 443 ssl http2; server_name localhost; # 其余配置略 }但从 Nginx 1.25.1 开始这种写法会提示弃用官方推荐的写法是拆成两条指令server { listen 443 ssl; http2 on; server_name localhost; # 其余配置略 }如果你用的是较新的 Nginx 版本建议直接使用http2 on;的新写法避免以后升级时收到一堆警告。WebSocket 代理是另一个高频场景。前端页面通过ws://或wss://连接后端Nginx 默认会直接断掉协议升级请求必须显式配置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; }这里的关键是把 HTTP 请求里的Upgrade头原样传给后端并且强制使用 HTTP/1.1HTTP/1.0 不支持协议升级。proxy_read_timeout记得设置长一点否则 WebSocket 空闲一段时间就会被 Nginx 掐断表现为“连接一会儿就断”。还有一个容易被忽略的小细节是 http 连接复用。Nginx 到后端服务默认使用 HTTP/1.0每次请求都会新建 TCP 连接性能很差。加上两行配置让 Nginx 复用和后端之间的连接location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Connection ; }本地调试时感知可能不明显但如果你在本地压测或者代理的服务本身 QPS 很高连接复用能明显降低延迟和资源占用。这个习惯建议从一开始就养成。4. 常见问题与排查要点4.1 证书报错与浏览器拦截这是本地 https 最常见的报错。现象是浏览器弹出NET::ERR_CERT_AUTHORITY_INVALID或者直接显示“您的连接不是私密连接”。排查顺序如下第一确认证书是否加入了系统信任区。前面讲了不同平台的方法这一步漏掉的概率最大。第二确认访问的域名和证书的 CN/SAN 是否匹配。证书签的是localhost你用127.0.0.1访问照样报错。第三确认证书有效期自签名证书设了 365 天到期后所有浏览器都会拦截需要重新生成并重新信任。我个人的习惯是把证书有效期统一设成 365 天并在日历里加一个提醒到期前一周重新生成。别用-days 3650长期有效的本地证书在某些新版本浏览器里反而会触发“证书策略异常”的提示得不偿失。注意修改系统信任区后需要完全关闭浏览器再重新打开。Chrome 对证书信任有缓存直接刷新页面有时不生效。4.2 502 Bad Gateway 与连接失败Nginx 配置好后访问报 502说明 Nginx 本身正常运行但没法把请求转发给后端。排查重点就一个后端服务到底有没有在监听。先用curl -v http://127.0.0.1:8080/health或netstat -an | grep 8080确认端口状态。如果后端没启动或者监听的地址不是127.0.0.1而是::1Nginx 连不上就会出现 502。很多开发框架默认监听 IPv6 地址而 Nginx 里proxy_pass写的是 IPv4这种“地址族不匹配”非常容易踩到。另一个常见原因是proxy_pass把端口写错了。后端监听在 8081你写成了 8080。这种低级错误最好用两分钟排查法先curl -v http://127.0.0.1:端口确认后端连通再curl -v https://localhost看 Nginx 层是否正常两步定位不要一上来就翻配置。还有一种情况是 WebSocket 连接出现 502多半是因为Upgrade头没传或者后端不支持协议升级。参考 3.4 节的配置补上即可。4.3 混合内容与端口占用配置好 https 之后页面打开发现部分资源仍然被拦比如图片、字体、CSS、接口请求。打开浏览器开发者工具Console 里会提示 Mixed Content 相关错误。排查思路看页面里所有资源的 URL 协议。如果 HTML 是 https 加载的但里面硬编码了http://的接口地址或资源地址浏览器就会拦。解决办法分三层尽快把代码里的地址改成协议相对写法比如//api.example.com让浏览器自动跟随当前协议这是最推荐的做法。如果资源地址是后端返回的检查后端生成链接时是否带了http。这就是为什么前面反复强调X-Forwarded-Proto后端拿到这个头才能正确生成 https 链接。如果实在改不动代码可以用 Nginx 再做一层代理把页面上引用的 http 资源也代理到 https 入口下。但这只是临时方案治标不治本。端口占用是另一个容易忽略的问题。本地多个服务同时监听了 443 端口Nginx 起不来报错形如bind() to 0.0.0.0:443 failed。排查时用lsof -i :443看看谁占用了端口常见冲突源是其他 Nginx 实例、Apache、或者某些 IDE 自带的静态服务器。杀掉占用进程或者给 Nginx 换一个端口监听。4.4 配置生效流程与开机自启很多同学改了nginx.conf之后直接关掉进程再重启这不是好习惯。正确的操作流程是nginx -t # 先检查语法 nginx -s reload # 再平滑重载配置reload会先完整校验配置再优雅重启工作进程已经建立的连接不会被中断。而直接 stop/start 会断开所有连接。本地影响可能不大但一旦养成这个习惯并带到生产环境就是在制造事故。关于 Linux 下的开机自启如果你是用 apt/yum 安装的 Nginx系统一般已经集成了 systemd 服务直接执行sudo systemctl enable nginx sudo systemctl start nginx如果是源码编译安装需要手动写一个 systemd service 文件或者把启动命令加到/etc/rc.local。我建议优先用 systemd因为可以方便地查看日志、配置失败自动重启策略。还有一个重要建议改完配置后如果 Nginx 行为不对劲第一件事不是反复翻配置而是看错误日志。大多数发行版的 Nginx 错误日志在/var/log/nginx/error.logmacOS 的 Homebrew 版本在/opt/homebrew/var/log/nginx/error.log。日志里会精确到哪一行配置、哪个上游连接出了问题比盲猜高效得多。5. 一份可以直接抄的完整配置模板最后给出一个完整的本地单项目配置模板包含 http 跳转、https 监听、反向代理、WebSocket、连接复用基本覆盖了本地开发的所有常见需求# /etc/nginx/conf.d/local-dev.conf # 80 端口全部跳转 https server { listen 80; server_name localhost; return 301 https://$host$request_uri; } # https 入口 server { listen 443 ssl; http2 on; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; client_max_body_size 50m; # 常规 http 服务 location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; 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_set_header Connection ; } # 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; } }注意client_max_body_size 50m;这一行建议从一开始就加上。Nginx 默认只允许 1MB 的请求体本地调试时传大文件、传图片、提交富文本内容很容易踩到 413 Request Entity Too Large 的错误。顺手加上能省掉很多莫名其妙的排查时间。把这份配置放入 Nginx 配置目录并通过include引入执行nginx -t确认语法再nginx -s reload加载。之后访问http://localhost会被自动跳转到https://localhost然后反向代理到本地 8080 服务整条链路就通了。最后再分享一个我自己坚持了很久的小习惯每次生成证书都把私钥路径、证书路径、配置文件的存放位置记在一个 README 文件里放在项目根目录。这样不管隔多久回来继续开发还是团队新人接手照着 README 五分钟就能把本地 https 环境搭起来。本地环境这种东西一旦断档重搭的成本远比你想象中高。
Nginx实现HTTP转HTTPS：本地开发环境配置指南
最近帮团队搭本地联调环境前后端同事差点吵起来。前端说接口全是 http 请求被浏览器拦得死死的后端说证书配置太麻烦根本不想碰。最后我直接用 Nginx 在本地做了一个 http 转 https 的统一入口前后花了不到十分钟两边都消停了。所谓 http 转 https本质上是让 Nginx 充当一个带 SSL 终结能力的反向代理客户端通过 https 访问 NginxNginx 解密后再把请求转发给背后跑着 http 服务的本地应用。后端代码一行不用改就完成了从明文到加密的切换。这篇文章我会把整套方案从头到尾过一遍为什么本地也需要 HTTPS、自签名证书怎么生成、Nginx 配置怎么写、多项目怎么分流、以及我这些年踩过的一堆坑。适合做 Web 开发、前后端联调、以及有本地环境维护需求的运维同学参考看完就能直接照抄。1. 方案思路为什么本地也得折腾 HTTPS1.1 本地开发逃不掉的三个场景先说说我为什么要折腾这件事。日常开发里你至少会遇到下面三种情况跑都跑不掉前端页面已经部署在 https 域名下浏览器会直接拦截从 https 页面发往 http 接口的请求这就是混合内容Mixed Content问题。打开 Chrome 控制台满屏都是 This request has been blocked。微信、小程序、某些 App 的 WebView 对 http 限制更严格不仅拦截有的直接白屏。想本地调试这类环境不搞 https 根本进不去。Cookie 的 Secure 属性。线上环境签发 Cookie 时带上了 Secure 标记本地 http 环境无法回传这种 Cookie登录态在本地直接失效。联调登录功能时最容易踩这个。这些问题的根源就是本地环境和线上环境的“协议不对称”。与其在代码里到处打补丁不如在入口处统一解决——这就是 Nginx 做 http 转 https 的价值把所有本地 http 服务统一收口到一个 https 入口后面前端、后端、联调脚本全部走同一条加密通道。1.2 HTTP 和 HTTPS 的真实区别很多同学对这两个协议的理解停留在“HTTPS 更安全”一句话上但做配置的时候你得知道它到底改了什么。HTTP 是明文协议客户端和服务器之间的请求、响应、Cookie、Token全部裸奔在网络里任何能截获流量的人都能直接看到内容。HTTPS 并不是一个全新协议它是 HTTP 和 TLS/SSL 的组合核心逻辑是先通过 TLS 握手完成身份验证和密钥协商之后所有 HTTP 数据都用对称加密传输。换句话说HTTPS 多出来的工作量全部集中在握手阶段。握手阶段有两件重要的事第一服务器向客户端出示数字证书证明“我是谁”第二双方协商出会话密钥后续数据全部走加密通道。这也解释了为什么本地开发要用自签名证书。证书的作用是身份证明自签名证书只是没有经过 CA证书颁发机构背书它在加密能力上和正规证书没有任何区别。本地调试完全够用唯一的问题是浏览器默认不认它手动信任一下就好。1.3 为什么选 Nginx 而不是其他工具本地实现 https 的方案其实不少我简单列一下对比方案适用场景缺点后端框架自带 TLS单个服务每个服务都要单独配改动侵入业务代码Node.js https 模块Node 服务只对 Node 生态有效Java/Go 等不适用Nginx 统一入口多服务、多项目需要懂一点 Nginx 配置但学习成本很低我推荐 Nginx 的核心原因有三个。一是收口本地可能有前端 dev server、后端 API、文件服务、Mock 服务等多个进程同时跑Nginx 一次性全部接管按域名或路径分流二是改动小后端服务完全不用感知 HTTPS代码一行不用动三是一致性线上生产环境通常也是 Nginx 做 SSL 终结本地和线上配置逻辑一致调试环境就相当于生产环境的缩小版排查思路可以无缝复用。2. 准备工作安装 Nginx、生成自签名证书2.1 不同平台下 Nginx 的安装方式Nginx 的安装方式根据操作系统不同略有差别我把常用的列出来macOS直接用 Homebrew执行brew install nginx。装完配置文件在/usr/local/etc/nginx/nginx.confIntel 芯片或/opt/homebrew/etc/nginx/nginx.confApple Silicon。Ubuntu/Debiansudo apt update sudo apt install nginx。配置文件在/etc/nginx/nginx.conf站点配置习惯放在/etc/nginx/sites-available/和/etc/nginx/sites-enabled/。CentOS/RHELsudo yum install nginx或sudo dnf install nginx配置主文件路径同样是/etc/nginx/nginx.conf。Windows去官网下载稳定版 zip 包解压后直接运行nginx.exe。Windows 下配置语法和 Linux 完全一致但注意没有守护进程改配置用nginx -s reload生效。我自己的习惯是本地项目单独建一份配置文件目录不在主配置文件里直接改而是用include把项目配置引进去。这样不同项目之间互不污染删除某个项目时直接把对应配置移除就行非常干净。提示装完先跑nginx -t验证语法再执行nginx -s reload。很多初学者改完配置直接重启语法报错会导致整个 Nginx 起不来这是一条被反复验证的教训。2.2 用 OpenSSL 一键生成自签名证书Nginx 做 https必须要有证书和私钥。本地调试不需要去 CA 机构申请用 OpenSSL 生成自签名证书就行一条命令搞定openssl req -x509 -newkey rsa:2048 -nodes \ -keyout localhost.key \ -out localhost.crt \ -days 365 \ -subj /CNlocalhost逐个解释关键参数req -x509生成自签名证书而不是生成证书签发请求CSR。newkey rsa:2048同时生成新的 RSA 密钥对长度 2048 位。2048 是当前最低推荐标准千万别用 1024浏览器会直接嫌弃。-nodes私钥不加密。生产环境不建议这么干但本地调试图方便。-keyout/-out分别指定私钥和证书的输出路径。-days 365有效期 365 天。macOS 的 Chrome 对超过 398 天的证书会直接报错所以设 365 天最稳。-subj /CNlocalhost证书的 Common Name。如果只是单机本地访问写localhost就够如果要用自定义域名比如dev.example.com这里要写域名并且 Nginx 配置里的server_name要和它一致。如果你想用局域网 IP 在手机上调试或者一个证书要覆盖多个域名就需要加 SANSubject Alternative Name扩展openssl req -x509 -newkey rsa:2048 -nodes \ -keyout localhost.key \ -out localhost.crt \ -days 365 \ -subj /CNlocalhost \ -addext subjectAltNameDNS:localhost,DNS:dev.example.com,IP:127.0.0.1,IP:192.168.1.100SAN 里可以混写 DNS 和 IP浏览器校验证书时优先看 SAN。如果你的页面会通过局域网 IP 被手机访问务必把 IP 加进去不然手机端永远报证书错误而且这种报错在电脑上还复现不出来非常坑。2.3 把自签名证书装进系统信任区生成完证书后直接访问 https://localhost 会被浏览器拦一大屏。原因前面说过证书没有 CA 签名浏览器无法验证身份。解决方案是把它加入系统信任区。macOS双击localhost.crt在“钥匙串访问”里导入选择“系统”钥匙串把证书的信任级别改为“始终信任”。Windows双击 crt 文件选择“安装证书”存储位置选“本地计算机”然后放到“受信任的根证书颁发机构”目录下。Ubuntusudo cp localhost.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates。移动端通过邮件或网盘把 crt 传给手机安装。iOS 安装后还要去“设置 - 通用 - 关于本机 - 证书信任设置”里打开开关Android 不同版本入口略有差异但逻辑基本一致。注意自签名证书只适合开发环境。如果用在生产环境用户会看到“不安全”警告而且一旦站点启用了 HSTS 等严格安全策略浏览器会直接拒绝连接。生产环境请走 Lets Encrypt 或云服务商的证书申请流程。3. 核心配置Nginx 实现 HTTP 转 HTTPS3.1 最基础的 SSL 终结配置证书和私钥就绪后先写一个最小的反向代理配置。假设本地有一个服务跑在127.0.0.1:8080我们需要让 Nginx 监听 443 端口以 https 接收请求然后转发到 8080server { listen 443 ssl; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { 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; } }这套配置的核心逻辑就是“SSL 终结”客户端和 Nginx 之间是加密的 httpsNginx 和后端服务之间是普通 http。后端代码完全不用管 TLS 的事只管处理业务逻辑。几个协议头是必须的Host $host保留原始请求的域名否则后端拿到的是127.0.0.1生成链接、做路由判断时都会出错。X-Real-IP和X-Forwarded-For把客户端真实 IP 传给后端。不加的话后端看到的全是 Nginx 本机地址日志和鉴权都会出问题。X-Forwarded-Proto $scheme告诉后端“原始请求是 https”。后端生成重定向、拼接回调地址时都会判断这个头少了它很容易出现“回调地址变成了 http”的诡异问题。3.2 HTTP 强制跳转 HTTPS 的三种写法光有 443 监听还不够用户访问http://localhost:8080时仍然走的是明文。通常我们要把 80 端口的请求强制跳转到 https。最简单、最常用的写法server { listen 80; server_name localhost; return 301 https://$host$request_uri; }这里return 301返回一个永久重定向$host和$request_uri会拼出完整的 https 地址。比如用户访问http://localhost/login会被重定向到https://localhost/login。第二种写法是用rewriteserver { listen 80; server_name localhost; rewrite ^(.*)$ https://$host$1 permanent; }效果上和return 301类似但官方更推荐用return。因为它直接返回重定向响应不走正则匹配性能更好语义也更清晰。我的建议是直接用return 301没有特殊情况不需要考虑 rewrite。第三种是只跳转特定路径。比如你只想让/api走 https其他路径放行可以在 80 端口的 location 里单独处理server { listen 80; server_name localhost; location /api { return 301 https://$host$request_uri; } location / { proxy_pass http://127.0.0.1:8080; } }对于本地调试我一般直接用全量跳转。但要注意如果你的后端接口同时存在 http 和 https 两种调用方式全量跳转会导致每次 http 请求都增加一次网络往返。本地无所谓生产环境需要斟酌。3.3 单机多项目怎么分流本地最常见的情况是同时跑好几个项目一个前端 dev server、一个后端 API、一个管理后台、一个文件服务。Nginx 的强项在于可以用一个 443 端口接收所有请求然后按域名或按路径分流到不同端口。按域名分流的配置server { listen 443 ssl; server_name project-a.local; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; } } server { listen 443 ssl; server_name project-b.local; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location / { proxy_pass http://127.0.0.1:4000; proxy_set_header Host $host; } }使用域名分流时需要改 hosts 文件把project-a.local和project-b.local指向127.0.0.1。macOS/Linux 的 hosts 文件在/etc/hostsWindows 在C:\Windows\System32\drivers\etc\hosts。这里有个重点证书 SAN 里必须包含这些域名否则浏览器照样报证书错误。按路径分流的配置server { listen 443 ssl; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; location /api/ { proxy_pass http://127.0.0.1:8080; } location /admin/ { proxy_pass http://127.0.0.1:9000; } location / { proxy_pass http://127.0.0.1:3000; } }按路径分流有个经典大坑proxy_pass后面有没有末尾斜杠行为完全不同。对比一下就明白了proxy_pass 写法请求 /api/user后端实际收到proxy_pass http://127.0.0.1:8080;/api/user/api/userproxy_pass http://127.0.0.1:8080/;/api/user/userproxy_pass http://127.0.0.1:8080/api/;/api/user/user也就是说proxy_pass末尾带斜杠Nginx 会把 location 匹配到的前缀剥掉再转发。这个细节经常导致接口 404排查半天最后发现是斜杠问题。我的建议是除了明确要做前缀剥离的场景一律不加末尾斜杠。3.4 进阶增强HTTP/2、WebSocket 与连接复用基础配置跑通之后有几个增强项值得加上能明显改善体验。HTTP/2 能显著提升页面加载速度尤其适合有大量并发请求的页面。老版本写法是在listen 443 ssl后面直接加http2参数server { listen 443 ssl http2; server_name localhost; # 其余配置略 }但从 Nginx 1.25.1 开始这种写法会提示弃用官方推荐的写法是拆成两条指令server { listen 443 ssl; http2 on; server_name localhost; # 其余配置略 }如果你用的是较新的 Nginx 版本建议直接使用http2 on;的新写法避免以后升级时收到一堆警告。WebSocket 代理是另一个高频场景。前端页面通过ws://或wss://连接后端Nginx 默认会直接断掉协议升级请求必须显式配置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; }这里的关键是把 HTTP 请求里的Upgrade头原样传给后端并且强制使用 HTTP/1.1HTTP/1.0 不支持协议升级。proxy_read_timeout记得设置长一点否则 WebSocket 空闲一段时间就会被 Nginx 掐断表现为“连接一会儿就断”。还有一个容易被忽略的小细节是 http 连接复用。Nginx 到后端服务默认使用 HTTP/1.0每次请求都会新建 TCP 连接性能很差。加上两行配置让 Nginx 复用和后端之间的连接location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Connection ; }本地调试时感知可能不明显但如果你在本地压测或者代理的服务本身 QPS 很高连接复用能明显降低延迟和资源占用。这个习惯建议从一开始就养成。4. 常见问题与排查要点4.1 证书报错与浏览器拦截这是本地 https 最常见的报错。现象是浏览器弹出NET::ERR_CERT_AUTHORITY_INVALID或者直接显示“您的连接不是私密连接”。排查顺序如下第一确认证书是否加入了系统信任区。前面讲了不同平台的方法这一步漏掉的概率最大。第二确认访问的域名和证书的 CN/SAN 是否匹配。证书签的是localhost你用127.0.0.1访问照样报错。第三确认证书有效期自签名证书设了 365 天到期后所有浏览器都会拦截需要重新生成并重新信任。我个人的习惯是把证书有效期统一设成 365 天并在日历里加一个提醒到期前一周重新生成。别用-days 3650长期有效的本地证书在某些新版本浏览器里反而会触发“证书策略异常”的提示得不偿失。注意修改系统信任区后需要完全关闭浏览器再重新打开。Chrome 对证书信任有缓存直接刷新页面有时不生效。4.2 502 Bad Gateway 与连接失败Nginx 配置好后访问报 502说明 Nginx 本身正常运行但没法把请求转发给后端。排查重点就一个后端服务到底有没有在监听。先用curl -v http://127.0.0.1:8080/health或netstat -an | grep 8080确认端口状态。如果后端没启动或者监听的地址不是127.0.0.1而是::1Nginx 连不上就会出现 502。很多开发框架默认监听 IPv6 地址而 Nginx 里proxy_pass写的是 IPv4这种“地址族不匹配”非常容易踩到。另一个常见原因是proxy_pass把端口写错了。后端监听在 8081你写成了 8080。这种低级错误最好用两分钟排查法先curl -v http://127.0.0.1:端口确认后端连通再curl -v https://localhost看 Nginx 层是否正常两步定位不要一上来就翻配置。还有一种情况是 WebSocket 连接出现 502多半是因为Upgrade头没传或者后端不支持协议升级。参考 3.4 节的配置补上即可。4.3 混合内容与端口占用配置好 https 之后页面打开发现部分资源仍然被拦比如图片、字体、CSS、接口请求。打开浏览器开发者工具Console 里会提示 Mixed Content 相关错误。排查思路看页面里所有资源的 URL 协议。如果 HTML 是 https 加载的但里面硬编码了http://的接口地址或资源地址浏览器就会拦。解决办法分三层尽快把代码里的地址改成协议相对写法比如//api.example.com让浏览器自动跟随当前协议这是最推荐的做法。如果资源地址是后端返回的检查后端生成链接时是否带了http。这就是为什么前面反复强调X-Forwarded-Proto后端拿到这个头才能正确生成 https 链接。如果实在改不动代码可以用 Nginx 再做一层代理把页面上引用的 http 资源也代理到 https 入口下。但这只是临时方案治标不治本。端口占用是另一个容易忽略的问题。本地多个服务同时监听了 443 端口Nginx 起不来报错形如bind() to 0.0.0.0:443 failed。排查时用lsof -i :443看看谁占用了端口常见冲突源是其他 Nginx 实例、Apache、或者某些 IDE 自带的静态服务器。杀掉占用进程或者给 Nginx 换一个端口监听。4.4 配置生效流程与开机自启很多同学改了nginx.conf之后直接关掉进程再重启这不是好习惯。正确的操作流程是nginx -t # 先检查语法 nginx -s reload # 再平滑重载配置reload会先完整校验配置再优雅重启工作进程已经建立的连接不会被中断。而直接 stop/start 会断开所有连接。本地影响可能不大但一旦养成这个习惯并带到生产环境就是在制造事故。关于 Linux 下的开机自启如果你是用 apt/yum 安装的 Nginx系统一般已经集成了 systemd 服务直接执行sudo systemctl enable nginx sudo systemctl start nginx如果是源码编译安装需要手动写一个 systemd service 文件或者把启动命令加到/etc/rc.local。我建议优先用 systemd因为可以方便地查看日志、配置失败自动重启策略。还有一个重要建议改完配置后如果 Nginx 行为不对劲第一件事不是反复翻配置而是看错误日志。大多数发行版的 Nginx 错误日志在/var/log/nginx/error.logmacOS 的 Homebrew 版本在/opt/homebrew/var/log/nginx/error.log。日志里会精确到哪一行配置、哪个上游连接出了问题比盲猜高效得多。5. 一份可以直接抄的完整配置模板最后给出一个完整的本地单项目配置模板包含 http 跳转、https 监听、反向代理、WebSocket、连接复用基本覆盖了本地开发的所有常见需求# /etc/nginx/conf.d/local-dev.conf # 80 端口全部跳转 https server { listen 80; server_name localhost; return 301 https://$host$request_uri; } # https 入口 server { listen 443 ssl; http2 on; server_name localhost; ssl_certificate /etc/nginx/ssl/localhost.crt; ssl_certificate_key /etc/nginx/ssl/localhost.key; client_max_body_size 50m; # 常规 http 服务 location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; 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_set_header Connection ; } # 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; } }注意client_max_body_size 50m;这一行建议从一开始就加上。Nginx 默认只允许 1MB 的请求体本地调试时传大文件、传图片、提交富文本内容很容易踩到 413 Request Entity Too Large 的错误。顺手加上能省掉很多莫名其妙的排查时间。把这份配置放入 Nginx 配置目录并通过include引入执行nginx -t确认语法再nginx -s reload加载。之后访问http://localhost会被自动跳转到https://localhost然后反向代理到本地 8080 服务整条链路就通了。最后再分享一个我自己坚持了很久的小习惯每次生成证书都把私钥路径、证书路径、配置文件的存放位置记在一个 README 文件里放在项目根目录。这样不管隔多久回来继续开发还是团队新人接手照着 README 五分钟就能把本地 https 环境搭起来。本地环境这种东西一旦断档重搭的成本远比你想象中高。
