FastifyWebSocketHTTPS配置问题解决方法

本文深入剖析了 Fastify 集成 @fastify/websocket 时 WSS 连接失败的核心症结——并非代码逻辑缺陷，而是 TLS 证书信任链缺失导致 WebSocket 握手在加密层即被浏览器或客户端中断；文章直击痛点，提供从本地开发（基于 mkcert 生成系统可信证书）到生产部署（配合 Let’s Encrypt 或反向代理的完整 HTTPS 配置）的双轨解决方案，并附上可直接运行的健壮代码、关键避坑指南及调试技巧，助你一次性打通 HTTPS 环境下稳定、安全、可信赖的 WebSocket 通信。

本文详解 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 失败”的典型陷阱。

今天关于《FastifyWebSocketHTTPS配置问题解决方法》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！