fiber v2需go≥1.21、v3需go≥1.24，go get必须显式带/v2或/v3后缀，否则降级或失败；混用版本会导致编译错误或运行时panic，应统一版本并检查go.mod。
确认 Go 版本再执行 go get
直接跑 go get github.com/gofiber/fiber/v2 却拉不到 v2？大概率是 Go 版本不匹配。Fiber v2 要求 Go ≥ 1.21，v3 要求 Go ≥ 1.24。用 go version 检查当前版本；若低于要求，go get 会静默降级到旧版（比如 v1.x），或根本解析失败。升级方式不是重装 Go，而是用 go install golang.org/dl/go1.24@latest && go1.24 download 切换测试——避免污染系统全局 Go 环境。
go get 命令必须带 /v2 或 /v3 后缀
漏写路径后缀是版本冲突最常见原因。Fiber 不遵循 Go 模块的语义化导入规则，github.com/gofiber/fiber 本身不指向任何稳定版本，必须显式指定：go get github.com/gofiber/fiber/v2。用 go get -u 更危险——它会尝试升级所有间接依赖，可能把 v2 升成 v3（或反之），导致 import 路径不一致、类型不兼容、函数找不到（比如 fiber.Default() 在 v3 中已移除）。
- 生产项目只用 v2：
go get github.com/gofiber/fiber/v2 - v3 仅限实验：
go get github.com/gofiber/fiber/v3，且需同步升级 Go 至 1.24+ - 绝不能混用：
import "github.com/gofiber/fiber/v2"和import "github.com/gofiber/fiber/v3"不能共存于同一模块
检查 go.mod 里的实际引入版本
运行 go get 后别只信终端输出，打开 go.mod 文件看真实记录。常见陷阱包括：
- 模块名写成
github.com/gofiber/fiber（缺/v2）→ Go 会 fallback 到伪版本如v1.12.0+incompatible，后续所有调用都报错 - 同一项目中不同子模块各自
go get了 v2 和 v3 →go mod tidy会报require github.com/gofiber/fiber: version ... has different major version than ... - 误删了
replace指令（曾用于本地调试）→ 导致构建时加载错误 commit hash
修复方法：删掉整行 fiber 相关 require，重新 go get 显式路径，再 go mod tidy。
v2 与 v3 的 import 和初始化差异必须对齐
版本冲突不只是依赖拉错，更常体现在代码里。v2 和 v3 的 API 差异已大到无法兼容：
- v2 中
fiber.Default()存在，v3 中已删除；v3 新增fiber.NewWithCustomCtx()，v2 没有 - v2 的中间件函数签名是
func(*fiber.Ctx) error，v3 改为func(fiber.Ctx)（无指针、无返回值） - 路由参数获取：v2 用
c.Params("id")，v3 统一为c.Params("id")（表面一样，但底层 ctx 类型完全不同）
一旦 go.mod 错配，编译会直接失败，错误信息通常是 cannot use ... (type *fiber.Ctx) as type fiber.Ctx 或 undefined: fiber.Default。此时不要硬改函数签名——先统一回 v2，再逐个替换初始化和中间件逻辑。
真正难排查的是跨模块引用：主项目用 v2，但某个内部 SDK 的 go.mod 锁定了 v3，go build 时不会报错，运行时却 panic。建议所有团队共享一份 .golangci.yml，用 govulncheck 或自定义 go list -m all 脚本定期扫描 fiber 版本一致性。
