fiber v2 是当前生产环境唯一推荐的稳定版本，需 go ≥ 1.21，安装命令为 go get github.com/gofiber/fiber/v2，import 路径和 go.mod 必须严格含 /v2，v3 尚属测试阶段不可混用。
Fiber v2 是当前生产环境唯一推荐的稳定版本，直接用 go get github.com/gofiber/fiber/v2 即可，但必须前置确认 Go 版本 ≥ 1.21。
Go 版本不达标会导致静默失败
运行 go version 检查当前版本。若低于 1.21（比如 go1.20.15），go get 不会报错，但可能拉取到不兼容的旧版 fiber（如 v1.x 或错误解析的 v2 分支），后续编译或运行时出现 undefined: fiber.New 或 cannot find package "github.com/gofiber/fiber/v2" 等问题。
- 升级方案：执行
go install golang.org/dl/go1.24@latest→go1.24 download→ 再用go1.24 version验证 - 不建议跳过验证——很多团队在 CI 流水线里因 Go 版本卡在 1.20 导致部署失败，排查耗时远超升级本身
import 路径和 go.mod 必须严格匹配 v2
安装后，在代码中必须使用 import "github.com/gofiber/fiber/v2"，且 go.mod 文件里对应依赖行应为：github.com/gofiber/fiber/v2 v2.52.0（具体版本号以实际拉取为准）。任何省略 /v2 或写成 /v2.0、/v2.52 的路径都会触发构建错误。
- 常见错误现象：
could not import github.com/gofiber/fiber (invalid use of internal package)—— 很可能是路径漏了/v2 - 如果项目之前用过 v1，需手动清理
go.sum中残留的 v1 条目，否则go mod tidy可能回退到旧版
v2 和 v3 绝对不能混用
即使本地装了 v3，只要项目 import 的是 /v2，就完全不受影响；反之亦然。但一旦在同一个模块里同时 import /v2 和 /v3，Go 会拒绝构建，并报错 duplicate import 或 mismatched versions。
- v3 当前（2026 年 10 月）仍属测试阶段，API 不稳定，
fiber.NewWithCustomCtx等新函数在某些中间件中尚未适配 - 如果你看到文档里写了
go get github.com/gofiber/fiber（无版本后缀），那基本是过时资料——这个命令默认拉 v1，已废弃多年
真正容易被忽略的是：很多团队在 Docker 构建阶段硬编码了 Go 版本（比如 golang:1.20-alpine），导致镜像内 go get 表面成功、实际失效。上线前务必在容器内执行一次 go list -m github.com/gofiber/fiber/v2 确认版本加载正确。
