WSS证书配置教程：WebSocketHTTPS使用指南

本文深入剖析了WSS（WebSocket Secure）连接失败的真正症结——绝大多数问题并非出在SSL证书本身，而是Nginx等中间代理未能正确透传WebSocket升级请求：关键在于必须精准配置`proxy_http_version 1.1`、`proxy_set_header Upgrade $http_upgrade`和`proxy_set_header Connection "upgrade"`三要素，任何拼写、引号或值的偏差都会导致浏览器发出的`101 Switching Protocols`握手被静默降级为普通HTTP 200响应；同时强调路径、域名、协议、SNI、证书SAN及文件格式（如fullchain.pem与无密码私钥）的端到端严格一致性，直击开发者调试时最易踩坑的代理头误配、相对路径失效、PFX未转换、斜杠差异和server_name不匹配等实战痛点。

WSS 连接失败，90% 的问题出在 Nginx 代理头没配对，而不是证书本身。 浏览器拒绝 wss:// 并不意味着证书错了，更可能是中间代理根本没把 WebSocket 升级请求传过去——它悄悄当普通 HTTP 请求处理了，连后端服务的边都没摸到。

为什么改了 wss:// 还连不上？

前端把 ws://example.com 改成 wss://example.com 只是第一步。HTTPS 环境下，浏览器强制要求：所有子资源（包括 WebSocket）必须走加密通道。但光有协议前缀还不够——从浏览器到你的 WebSocket 服务之间如果经过 Nginx、CDN 或负载均衡器，它们必须识别并透传 WebSocket 的升级信号。

常见现象：

• 控制台报错 WebSocket connection to 'wss://...' failed，网络面板里该连接状态码是 200 而不是 101
• 后端日志完全收不到 upgrade 事件，说明请求压根没被当成 WebSocket 处理
• Nginx access log 显示该请求走了 GET /path，且 status 是 200，而非协议升级流程

proxy_set_header Upgrade $http_upgrade 必须写对

这是 Nginx 代理 WebSocket 最容易写错的一行。它不是可选项，而是协议握手生效的前提。

正确写法（注意变量名和引号）：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

错误写法示例：

• proxy_set_header Upgrade websocket; —— 硬编码会破坏客户端生成的 Sec-WebSocket-Key 校验
• proxy_set_header Connection upgrade; —— 缺少双引号，Nginx 会把它当字符串字面量而非指令值，实际不生效
• proxy_set_header Connection "keep-alive, upgrade"; —— 多余字段干扰升级逻辑，部分旧版 Nginx 会直接拒绝

额外建议：

• 加上 proxy_http_version 1.1;，WebSocket 升级依赖 HTTP/1.1
• 如果后端是集群或带路径前缀（如 /ws），proxy_pass 末尾不要加斜杠，否则路径会被重写

证书路径和格式不能只靠“看着像”

Node.js 启动 wss 服务时若直接用 HTTPS Server 托管 WebSocket（即不用 Nginx 代理），证书路径写错会导致进程启动失败或握手静默中断。

关键点：

• fs.readFileSync() 读取的必须是绝对路径，相对路径在 systemd 或 pm2 下极易失效
• 证书文件推荐用 fullchain.pem（含中间证书），不是单独的 cert.pem；私钥必须是未加密的 privkey.pem，带密码的 key 会导致 Node.js 启动卡住
• 如果你用的是 .pfx 或 .p12（比如 Windows 自签名场景），Node.js 不原生支持，得先用 OpenSSL 转成 PEM：
  openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -nodes -out key.pem

客户端 URL 和服务端监听必须严格一致

哪怕只差一个斜杠，wss://api.example.com/ws 和 wss://api.example.com/ws/ 在 Nginx 或 ws.Server 配置中可能被路由到不同分支，导致 404 或降级为 HTTP。

检查项：

• 前端 new WebSocket('wss://...') 中的域名、端口、路径，必须和服务端 server.on('upgrade', ...) 监听的路径完全匹配
• 如果用了 Nginx 代理，location /ws { proxy_pass http://localhost:3000; } 表示后端收到的原始 path 是 /ws，不是 /；后端 ws.Server({ noServer: true }) 的 handleUpgrade 必须基于这个路径做判断
• 证书的 Common Name 或 SAN 必须覆盖你实际访问的域名；用 IP 直连 wss://192.168.1.100 时，自签名证书必须显式包含该 IP（普通域名证书不认 IP）

最常被忽略的一点：Nginx 的 server_name 和客户端 URL 域名不一致（比如配置了 server_name www.example.com，但用户访问的是 example.com），会导致 SSL 握手成功但后续升级失败——因为 SNI 匹配不上，Nginx 可能 fallback 到默认 server，而那个 server 没配 WebSocket 头。

本篇关于《WSS证书配置教程：WebSocketHTTPS使用指南》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！