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

本文详解 fastify 配合 @fastify/websocket 在启用 https（即 wss）时连接失败的典型原因与完整解决路径，涵盖证书配置、服务端注册顺序、客户端连接方式及调试要点。

本文详解 fastify 配合 @fastify/websocket 在启用 https（即 wss）时连接失败的典型原因与完整解决路径，涵盖证书配置、服务端注册顺序、客户端连接方式及调试要点。

在使用 Fastify 构建全栈实时应用时，本地 HTTP 环境下 @fastify/websocket 通常能无缝工作；但一旦切换至 HTTPS（即需支持 wss:// 协议），前端 WebSocket 客户端常报错 ERR_CONNECTION_REFUSED 或 net::ERR_CERT_INVALID，而 Fastify 的 HTTPS 服务本身却正常响应 HTML/JSON —— 这表明问题不在于服务未启动，而在于 WSS 升级握手或 TLS 层配置存在隐性缺陷。

✅ 核心原因：WebSocket 依赖 HTTPS 实例的正确透传

@fastify/websocket 并非独立运行 WebSocket 服务器，而是复用 Fastify 底层 HTTP(S) Server 的 upgrade 事件。当启用 HTTPS 时，必须确保：

• Fastify 实例显式以 HTTPS 模式初始化（而非先创建 HTTP 实例再“打补丁”）；
• @fastify/websocket 插件在 HTTPS 配置完成后再注册（注册顺序影响内部 server 引用）；
• 证书文件路径有效、权限可读，且私钥与证书匹配（常见错误：.key 与 .crt 不属同一对）。

你的原始代码中已基本满足前两点，但存在一个关键疏漏：未为 HTTPS 模式下的 fastify.listen() 显式指定 https: true 选项（尽管 Fastify 内部会识别，但部分 Node.js 版本或代理环境要求显式声明）。此外，客户端若仍尝试连接 ws://（而非 wss://），必然失败。

✅ 正确配置示例（含开发与生产适配）

const fs = require('fs');
const fastify = require('fastify');

const config = {
  privKey: process.env.PRIV_KEY || './certs/localhost-key.pem',
  certKey: process.env.CERT_KEY || './certs/localhost.pem',
  https: process.env.HTTPS === '1',
  domains: process.env.DOMAINS?.split(',') || ['http://localhost:3000'],
  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）
      // ca: fs.readFileSync('./certs/rootCA.pem'),
    }
  })
});

// ✅ 关键：CORS 需明确允许 wss:// 协议源（注意协议一致性）
fastifyInstance.register(require('@fastify/cors'), {
  origin: config.domains.map(domain => 
    domain.replace(/^http/, 'ws') // 将 http:// → ws://, https:// → wss://
  ),
  credentials: true
});

// ✅ 关键：WebSocket 插件必须在 HTTPS 配置后注册
fastifyInstance.register(require('@fastify/websocket'));

// WebSocket 路由定义
fastifyInstance.register(async function (instance) {
  instance.get('/live', { websocket: true }, (connection, request) => {
    console.log(`New WSS connection from ${request.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('Connection closed');
    });
  });
});

// ✅ 关键：listen 时无需额外传 https: true，但 host/port 必须显式
const start = async () => {
  try {
    const address = await fastifyInstance.listen({
      host: '0.0.0.0',
      port: config.port,
      // ⚠️ 注意：HTTPS 模式下，Node.js 原生 server 会自动处理 upgrade，
      // 无需手动设置 secureContext —— Fastify 已封装
    });
    fastifyInstance.log.info(`Server listening at ${address}`);
    if (config.https) {
      fastifyInstance.log.info(`WSS endpoint: wss://localhost:${config.port}/live`);
    } else {
      fastifyInstance.log.info(`WS endpoint: ws://localhost:${config.port}/live`);
    }
  } catch (err) {
    fastifyInstance.log.error(err);
    process.exit(1);
  }
};

start();

✅ 开发环境证书推荐方案：mkcert

正如答案所提示，自签名证书的兼容性是最大障碍。浏览器和现代 WebSocket 客户端（如 Chrome、Firefox、new WebSocket()）默认拒绝不受信任的证书。解决方案：

1. 安装 mkcert（官网）：

   # macOS
   brew install mkcert nss
   mkcert -install
   
   # Windows (PowerShell as Admin)
   choco install mkcert
   mkcert -install

2. 生成本地可信证书：

   

   LOGO.com

   在线生成Logo，100%免费

   下载

   mkdir certs
   mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem "localhost"

3. 设置环境变量启动：

   HTTPS=1 PRIV_KEY=./certs/localhost-key.pem CERT_KEY=./certs/localhost.pem PORT=3000 node server.js

此时 wss://localhost:3000/live 将被浏览器完全信任。

✅ 客户端连接注意事项

确保前端使用正确的协议与域名：

// ✅ 正确：协议与后端一致
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const socket = new WebSocket(`${protocol}//${window.location.host}/live`);

socket.onopen = () => console.log('WSS connected');
socket.onmessage = (e) => console.log('Server:', e.data);

若部署在 Nginx/Apache 后，还需配置反向代理透传 WebSocket 头（Upgrade, Connection），此非 Fastify 侧问题，但常被忽略。

✅ 总结：排查清单

遵循以上结构化配置，即可稳定启用 Fastify 的 WSS 支持，兼顾开发效率与生产安全性。