本文详解 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 配置被完整、一致地传递，且证书对客户端可信。
以下为优化后的生产就绪配置示例（含错误防护与调试建议）：
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
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 失败”的典型陷阱。
