fiber v2 与 v3 切换不可仅靠 git checkout，因模块路径、go 版本要求、strictrouting 移除、locals 类型变更及 ctx.next() 语义差异导致编译或运行失败。
直接切换 Fiber 版本不是“git checkout 一下就能用”的事——fiber.Default() 在 v2 和 v3 之间行为不兼容，go mod 不会自动帮你处理中间件签名变更、ctx.Next() 语义差异或 StrictRouting 默认值变化。你切分支后跑不起来，大概率卡在这三处。
为什么 go mod tidy 不能解决多分支 Fiber 版本切换
Fiber v2（推荐生产）和 v3（测试阶段）是不同模块路径：github.com/gofiber/fiber/v2 vs github.com/gofiber/fiber/v3。但问题不在 import 路径——而在于：
- v3 要求 Go ≥ 1.24，你的项目若用 Go 1.22 或 1.23，
go build直接报错，不会等你写完 handler - v2 的
fiber.Config{StrictRouting: true}是默认值；v3 中该字段已移除，改由路由注册时显式控制，旧配置 struct 会编译失败 - v2 的
ctx.Locals是 map[string]any；v3 中底层类型变为sync.Map，若你有直接类型断言ctx.Locals["key"].(map[string]string)，运行时 panic
安全切换 Fiber 分支的实操步骤
别依赖全局 GOPATH 或反复 go install。每个分支应绑定独立的模块依赖快照：
- 进分支前先确认 Go 版本：
go version—— v2 分支用 Go 1.19–1.23，v3 分支必须切到 Go 1.24+ - 删掉
go.sum和vendor/（如有），再执行：go mod tidy -compat=1.23（v2）或go mod tidy -compat=1.24（v3） - 检查
main.go初始化方式：v2 分支必须用fiber.New()，禁用fiber.Default()；v3 分支需替换所有ctx.Next()前的响应写入逻辑——v3 中它不再隐式跳过已响应的 handler - 运行前加一道校验：
go run -gcflags="-l" .快速编译检查符号是否缺失（比如 v3 中已删除的fiber.NewWithConfig）
如何避免切换时漏掉中间件兼容性问题
你写的中间件很可能在 v2 和 v3 间失效，尤其涉及：
-
ctx.Request().URI().Path()返回值：v2 返回带原始编码的路径（如%20），v3 默认 decode 后返回（空格变 -
app.Use("/api", middleware)的匹配逻辑：v2 中该中间件只触发/api/*，v3 中会匹配/api本身（无尾斜杠），若你中间件里有c.Next()+c.Status(404)组合，v3 下可能提前终止链路 - 自定义日志中间件若调用了
c.Response().StatusCode()，v3 中该方法已重命名为c.Response().GetStatusCode()
最省事的办法：每个分支维护一个 fiber-version-check.go 文件，里面只放三行能暴露 breaking change 的代码，CI 阶段强制跑一遍。
