Fastify WebSocket 与 HTTPS 配置失效的完整解决方案

本文详解 fastify 结合 @fastify/websocket 在启用 https（即 wss）时连接失败的根本原因，指出证书信任链缺失是主因，并提供本地开发与生产环境的双轨配置方案，含可运行代码、证书生成指南及关键注意事项。

本文详解 fastify 结合 @fastify/websocket 在启用 https（即 wss）时连接失败的根本原因，指出证书信任链缺失是主因，并提供本地开发与生产环境的双轨配置方案，含可运行代码、证书生成指南及关键注意事项。

在使用 @fastify/websocket 构建 WebSocket 服务时，HTTP 环境下 ws:// 连接通常能正常工作，但一旦启用 HTTPS（即切换至 wss://），客户端频繁报错如 ERR_CONNECTION_REFUSED 或 net::ERR_CERT_INVALID，而 Fastify 的 HTTPS 服务本身仍可响应普通 HTTPS 请求——这明确指向 WebSocket 协议层未正确继承或识别 TLS 上下文，而非服务未启动。

根本原因并非代码逻辑错误，而是 TLS 证书的信任状态不被客户端认可：

• 浏览器/现代客户端强制要求 WSS 使用受信证书（如 Let’s Encrypt 或企业 CA 签发）；
• 自签名证书或私有 CA 证书（如 OpenSSL 手动生成）默认不被信任，导致 WebSocket 握手在 TLS 层即被中断；
• @fastify/websocket 本身不处理证书验证，它完全依赖底层 Node.js https.Server 的 TLS 配置——只要 Fastify 启动时传入了正确的 https 选项，WSS 就自动启用，无需额外注册或中间件。

✅ 正确做法：确保 Fastify 的 https 配置被完整、一致地传递，且证书对客户端可信。

以下为优化后的生产就绪配置示例（含错误防护与调试建议）：

const fs = require('fs'); const fastify = require('fastify'); const websocketPlugin = require('@fastify/websocket'); const cors = require('@fastify/cors');  const config = {   https: process.env.HTTPS === '1',   privKey: process.env.PRIV_KEY,   certKey: process.env.CERT_KEY,   domains: process.env.DOMAINS?.split(',') || ['http://localhost:3000'],   port: parseInt(process.env.PORT) || 3000, };  // ✅ 关键：统一构建 Fastify 实例，避免条件式 require 导致模块缓存/初始化差异 const app = fastify({   serverTimeout: 60 * 60 * 1000,   logger: true,   // 若启用 HTTPS，必须在此处注入 https 配置   ...(config.https && {     https: {       key: fs.readFileSync(config.privKey),       cert: fs.readFileSync(config.certKey),       // 生产环境建议添加 ca（如使用中间证书）       // ca: fs.readFileSync('fullchain.pem'),     }   }) });  // ✅ CORS 需显式允许 WSS 协议来源（Origin 可为 ws:// 或 wss://，但浏览器发送的 Origin 是页面协议） await app.register(cors, {   origin: config.domains,   credentials: true });  // ✅ WebSocket 插件注册必须在 HTTPS 配置之后，且无需额外参数 await app.register(websocketPlugin);  // ✅ WebSocket 路由定义（注意：路径需与前端 new WebSocket('wss://.../live') 严格一致） app.get('/live', { websocket: true }, (connection, req) => {   console.log(`New WebSocket connection from ${req.socket.remoteAddress}`);    connection.socket.on('message', (data) => {     try {       const msg = data.toString();       console.log('Received:', msg);       connection.socket.send(`Echo: ${msg}`);     } catch (err) {       console.error('Send error:', err);     }   });    connection.socket.on('close', () => {     console.log('Client disconnected');   }); });  // ✅ listen() 必须匹配协议：HTTPS 服务需监听 HTTPS 端口（通常 443），且 host 不应为 '0.0.0.0' 在容器外暴露时需谨慎 const start = async () => {   try {     const address = await app.listen({       host: '0.0.0.0',       port: config.port,       // ⚠️ 重要：HTTPS 下，listen() 不会自动降级；若端口非 443，请确保反向代理（nginx/Caddy）已将 443 → 本机端口转发       listenTextResolver: (addr) => `Server listening at ${addr}`     });     app.log.info(`Server running on ${address}`);   } catch (err) {     app.log.error(err);     process.exit(1);   } };  start();

? 本地开发推荐方案：使用 mkcert 生成本地可信证书
mkcert 创建的证书会被系统/浏览器自动信任，完美解决 WSS 证书警告问题：

# 安装 mkcert（macOS 示例） brew install mkcert nss  # 初始化本地 CA mkcert -install  # 为 localhost 生成证书（适用于 wss://localhost:3000/live） mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1

然后设置环境变量：

export HTTPS=1 export PRIV_KEY=./key.pem export CERT_KEY=./cert.pem export PORT=3000 export DOMAINS="http://localhost:3000" node server.js

? 关键注意事项总结：

• ❌ 不要混合使用 HTTP 和 HTTPS 的 Fastify 实例；始终用同一实例承载所有协议；
• ❌ 不要在 fastify.register() 中动态判断是否加载 @fastify/websocket——插件注册时机不影响 TLS 继承，但逻辑混乱易引入 bug；
• ✅ 前端连接 URL 必须与后端协议严格匹配：https:// 页面只能连接 wss://，http:// 页面只能连 ws://（混合协议被浏览器阻止）；
• ✅ 生产环境务必使用 Let’s Encrypt（推荐通过 Caddy/Nginx 自动签发），避免手动管理证书过期；
• ✅ 启用 app.log.level = ‘trace’ 可捕获 WebSocket 升级请求细节（如 onRequest 日志中查看 Upgrade: websocket 头是否存在）。

通过以上配置，Fastify 的 WSS 支持将稳定可靠，彻底规避“HTTPS 正常但 WSS 失败”的典型陷阱。