Fastify WebSocket 连接在 HTTPS 下失败的完整解决方案

本文详解 fastify 配合 @fastify/websocket 在启用 https（wss）时连接失败的常见原因与实战修复方案，涵盖证书配置、服务器初始化逻辑、客户端连接注意事项及调试技巧。

本文详解 fastify 配合 @fastify/websocket 在启用 https（wss）时连接失败的常见原因与实战修复方案，涵盖证书配置、服务器初始化逻辑、客户端连接注意事项及调试技巧。

在使用 Fastify 构建全栈实时应用时，@fastify/websocket 是官方推荐的 WebSocket 插件，但许多开发者在从 HTTP 切换到 HTTPS 后会遇到 ws:// 可连而 wss:// 无法建立连接的问题——服务端日志无报错、HTTPS 页面正常加载，但浏览器控制台提示 net::ERR_CONNECTION_REFUSED 或 Error during WebSocket handshake: net::ERR_SSL_PROTOCOL_ERROR。这并非插件兼容性问题，而是 HTTPS/WSS 协议协同中的典型配置疏漏。

✅ 正确初始化 Fastify 实例（关键！）

首要问题是：WebSocket 支持必须与 HTTPS 配置同步注入 Fastify 实例。你当前的代码中，@fastify/websocket 是在 https: {…} 选项外注册的，看似无害，但 Fastify 的 WebSocket 插件依赖底层 server 实例的协议能力。若 https 配置未在 fastify() 构造时传入，即使后续监听 HTTPS 端口，WebSocket 升级（upgrade）请求仍可能被降级处理或拒绝。

请统一使用以下初始化方式（推荐单实例 + 条件化配置）：

const fs = require('fs'); const fastify = require('fastify');  const config = {   privKey: process.env.PRIV_KEY,   certKey: process.env.CERT_KEY,   https: process.env.HTTPS === '1',   domains: process.env.DOMAINS?.split(',') || ['*'],   port: parseInt(process.env.PORT) || 3000, };  // 统一构建 Fastify 实例（HTTPS 配置必须在此处声明） const fastifyInstance = fastify({   serverTimeout: 60 * 60 * 1000,   logger: true,   ...(config.https && {     https: {       key: fs.readFileSync(config.privKey),       cert: fs.readFileSync(config.certKey),       // ⚠️ 生产环境建议添加 ca（如使用中间证书）       // ca: fs.readFileSync('./fullchain.pem'),     }   }) });  // ✅ 此时再注册 CORS 和 WebSocket（顺序无关紧要，但必须在 listen() 前） fastifyInstance.register(require('@fastify/cors'), {   origin: config.domains, });  fastifyInstance.register(require('@fastify/websocket'));  // WebSocket 路由注册 fastifyInstance.register(async function (instance) {   instance.get('/live', { websocket: true }, (connection, request) => {     console.log('New WebSocket connection from:', request.socket.remoteAddress);      connection.socket.on('message', (data) => {       try {         const message = data.toString();         console.log('Received:', message);         connection.socket.send(`Echo: ${message}`);       } catch (err) {         console.error('Send error:', err);       }     });      connection.socket.on('close', () => {       console.log('Connection closed');     });   }); });  // 启动监听（自动适配 http(s)） const start = async () => {   try {     const address = await fastifyInstance.listen({       host: '0.0.0.0',       port: config.port,       // ⚠️ 重要：HTTPS 模式下必须显式指定 secure: true（否则默认走 HTTP）       ...(config.https && { secure: true })     });     fastifyInstance.log.info(`Server listening at ${address}`);   } catch (err) {     fastifyInstance.log.error(err);     process.exit(1);   } };  start();

? 证书要求：WSS 不接受自签名证书（除非显式信任）

你提到“证书有效，Fastify HTTPS 工作正常”，但需注意：浏览器对 wss:// 的 TLS 校验比 https:// 更严格。即使页面通过 https:// 加载，WebSocket 连接仍会独立校验证书链完整性。

• ❌ 浏览器直接拒绝未受信的自签名证书（如 OpenSSL 生成的），且不会弹出“继续访问”提示；

• ✅ 推荐开发环境使用 mkcert 生成本地可信证书：

  # 安装并初始化本地 CA mkcert -install # 为 localhost 生成证书 mkcert localhost 127.0.0.1 ::1 # 输出：localhost-key.pem + localhost.pem

  将生成的 .pem 文件路径赋给 PRIV_KEY 和 CERT_KEY 环境变量即可。

• ? 生产环境务必使用 Let’s Encrypt（certbot）或云厂商签发的完整证书链（含 fullchain.pem），避免因缺少中间证书导致 WSS 握手失败。

? 客户端连接：协议必须严格匹配

前端连接时，务必确保 URL 协议与服务端一致：

// ✅ 正确：HTTPS 页面 → WSS 连接 const ws = new WebSocket('wss://your-domain.com/live');  // ❌ 错误：HTTPS 页面尝试 ws://（混合内容被浏览器阻止） // const ws = new WebSocket('ws://your-domain.com/live'); // Blocked by browser!  // ✅ 开发环境（localhost + mkcert） const ws = new WebSocket('wss://localhost:3000/live');

? 提示：Chrome 控制台 > Application > Frames 中可查看当前页面协议，确保 wss:// 连接来源与页面同源（协议+域名+端口）。

? 调试技巧

1. 验证 HTTPS 是否真正启用：
   curl -I https://localhost:3000 应返回 HTTP/2 200 或 HTTP/1.1 200，且无证书警告。

2. 测试 WSS 握手（命令行）：

   # 使用 wscat（npm install -g wscat） wscat -c "wss://localhost:3000/live" --insecure  # --insecure 仅开发时跳过证书校验

3. 检查 Fastify 日志级别：
   启用详细日志：logger: { level: ‘trace’ }，观察是否有 upgrade 请求被拦截或 websocket: false 相关 warn。

✅ 总结：WSS 连接成功的三大前提

遵循以上方案，99% 的 Fastify + WSS 连接问题将迎刃而解。记住：WSS 不是“HTTPS 上的 WS”，而是基于 TLS 的独立协议通道，其握手、证书、端口均需端到端对齐。