Fiber 版本必须显式锁死在 go.mod 中，否则 go get 会静默拉取最新兼容版导致 v2/v3 混用编译失败；需用 require + replace 双保险锁死具体 patch 版本，并统一初始化逻辑。
Fiber 版本必须显式锁死在 go.mod 中，不能靠团队口头约定或文档说明——否则 go get 会静默拉取最新兼容版，v2 和 v3 混用直接导致编译失败。
为什么 go get github.com/gofiber/fiber/v2 不够用
执行该命令只会在本地 go.mod 写入类似 github.com/gofiber/fiber/v2 v2.52.0 的行，但这个版本号是 go get 当前解析出的“最新 tagged 版本”，不是你项目实际测试过的稳定版。CI/CD 构建时若远程模块未锁定，go mod download 可能拉到 v2.53.0（含不兼容变更），而本地开发仍卡在 v2.52.0，环境不一致问题立刻暴露。
- 团队成员各自
go get后，go.mod里版本号可能不同 - 依赖传递中，某个子模块间接引入
fiber/v3，而主模块用v2，Go 报错：cannot use *fiber.Ctx (type *v2.Ctx) as type *v3.Ctx -
go list -m all | grep fiber显示多个版本共存，说明模块图已污染
正确做法：用 require + replace 双保险
所有协作项目统一在根 go.mod 中写死版本，并禁止自动升级：
- 显式
require github.com/gofiber/fiber/v2 v2.52.0（填你们验证过的具体 patch 版本） - 加
replace github.com/gofiber/fiber/v2 => github.com/gofiber/fiber/v2 v2.52.0，强制所有间接依赖也走这个精确版本 - CI 流水线中加入检查脚本：
grep -q "github.com/gofiber/fiber/v2 v2.52.0" go.mod || exit 1
别信 // indirect 标记——它只表示“未被当前模块直接 import”，不代表安全；只要 go.mod 里没明文锁死，就存在漂移风险。
跨项目共享配置时，fiber.New() 初始化逻辑也要标准化
不同项目若都用 fiber.Default() 或随意加载中间件，会导致行为不一致（比如日志格式、错误堆栈开关、StrictRouting 状态）。建议抽一个内部包，如 github.com/yourorg/fiberkit，导出统一初始化函数：
func NewApp() *fiber.App {
return fiber.New(fiber.Config{
StrictRouting: true,
CaseSensitive: true,
ServerHeader: "YourApp",
})
}
各项目只调 fiberkit.NewApp()，不自己拼 fiber.New() 参数——这样版本统一不只是依赖层面，更是运行时行为层面的收敛。
最容易被忽略的是：v2 和 v3 的 import 路径完全不同，且 Go 不允许同一项目中同时存在 github.com/gofiber/fiber/v2 和 github.com/gofiber/fiber/v3；一旦某个协作者本地误装 v3，go mod tidy 就会把整个模块树拖进不兼容状态，修复成本远高于初期锁死。
