Fiber v2不内置WebSocket支持，需用github.com/gofiber/websocket/v2适配器；注册路由须用websocket.New()包装handler，路径仅限GET且禁用干扰Upgrade头的中间件；广播需协程+channel避免并发写panic；CORS、反代配置及心跳保活是常见问题关键。
WebSocket连接为什么在Fiber里不能直接用ctx.WebSocket()？
Fiber官方v2主干不内置WebSocket支持，ctx.WebSocket()根本不存在——这是新手最常卡住的第一步。Fiber定位是HTTP框架，WebSocket属于长连接协议，需要靠第三方适配器桥接。目前最稳定的选择是github.com/gofiber/websocket/v2，它封装了gorilla/websocket底层，与Fiber路由机制兼容良好。
注意：websocket/v2和Fiber主版本要对齐（Fiber v2.x → websocket/v2；Fiber v3未正式发布前别盲目升级）。安装命令必须带/v2后缀：
go get github.com/gofiber/websocket/v2
如何注册WebSocket路由并处理连接升级？
Fiber的Get路由可以接收Upgrade请求，但必须用websocket.New()包装处理器，否则会返回400 Bad Request或405 Method Not Allowed。关键点在于：不能在普通func(c *fiber.Ctx) error里调用c.WebSocket()（这方法压根不存在），而要传入一个websocket.Handler类型函数。
典型写法：
立即学习“go语言免费学习笔记（深入）”；
import "github.com/gofiber/websocket/v2"
<p>app.Get("/ws", websocket.New(func(c *websocket.Conn) {
// 连接已建立，c.ReadMessage() / c.WriteMessage() 可用
for {
_, msg, err := c.ReadMessage()
if err != nil {
break // 客户端断开或网络错误
}
c.WriteMessage(websocket.TextMessage, msg)
}
}))- 路径
/ws必须是GET方法，且不能有中间件修改响应头（比如Logger或Compress可能干扰Upgrade头） -
websocket.New()返回的是fiber.Handler，可直接塞进app.Get() - 连接生命周期由
c对象管理，不要试图在外部保存*websocket.Conn指针并发读写——它不是线程安全的
如何安全地广播消息给所有客户端？
WebSocket本身不提供广播能力，需自行维护连接池。常见错误是用map存*websocket.Conn然后遍历调用WriteMessage，但WriteMessage可能阻塞，且并发写同一连接会panic。正确做法是为每个连接启动独立读/写协程，并用channel收发消息。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
精简示例结构：
var clients = make(map[*websocket.Conn]bool)
var broadcast = make(chan []byte)
<p>func handleWS(c *websocket.Conn) {
clients[c] = true
defer func() {
delete(clients, c)
c.Close()
}()</p><pre class='brush:php;toolbar:false;'>// 写协程：从broadcast channel取消息发给当前连接
go func() {
for msg := range broadcast {
if err := c.WriteMessage(websocket.TextMessage, msg); err != nil {
return
}
}
}()
// 读协程：接收客户端消息，转发到广播channel
for {
_, msg, err := c.ReadMessage()
if err != nil {
break
}
broadcast <- msg
}}
- 务必用
defer清理clients映射，否则内存泄漏 - 不要在
for循环里直接c.WriteMessage()——写操作可能慢于读，导致协程堆积 -
broadcastchannel最好带缓冲（如make(chan []byte, 100)），避免发送方被阻塞
为什么客户端频繁报connection closed或invalid header？
多数是HTTP头不匹配或跨域问题。Fiber默认不设置Access-Control-Allow-Origin，浏览器WebSocket握手会因CORS失败；另外，某些代理（Nginx、Cloudflare）会吞掉Upgrade头或重置连接。
解决步骤：
- 开发阶段加CORS中间件：
app.Use(cors.New())（用github.com/gofiber/cors/v3），生产环境建议精确配置AllowOrigins - Nginx反向代理必须显式透传头：
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade" - 检查客户端URL是否带
ws://（HTTP）或wss://（HTTPS）——混用协议必然失败 - 用
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:3000/ws手动测试握手，看是否返回101 Switching Protocols
真正难调试的是连接空闲超时：gorilla/websocket默认60秒无消息就关连接，Fiber层无法干预，只能在handleWS里定期发Ping保活。
