必须使用 Go ≥ 1.21 且执行 go get github.com/gofiber/fiber/v2（带/v2后缀），否则会静默拉取 v1 分支导致编译失败；升级推荐 go install golang.org/dl/go1.24@latest 后运行 go1.24 download；初始化用 fiber.New() 而非 fiber.Default() 以避免冗余依赖。
go version 不够新，go get 会静默失败
运行 go get github.com/gofiber/fiber/v2 前，必须确认 Go 版本 ≥ 1.21。用 go version 检查；若显示 go1.20.15 或更低，go get 仍会执行但实际拉取的是 v1 兼容分支（已归档），后续 import github.com/gofiber/fiber/v2 时编译报错：cannot find package "github.com/gofiber/fiber/v2"。
升级方式（推荐）：
- 执行
go install golang.org/dl/go1.24@latest（v2 兼容，且为当前稳定最新） - 再运行
go1.24 download - 最后用
go1.24 version确认生效
go get 命令必须带 /v2 后缀
不写版本后缀会导致模块路径解析错误，go.mod 中记录的依赖变成 github.com/gofiber/fiber（无版本），后续任何 go build 或 go run 都可能因 GOPROXY 缓存拉取到废弃的 v1 版本。
正确命令只有一条：
-
go get github.com/gofiber/fiber/v2（生产唯一推荐） - 别用
go get -u——它会强制升级所有间接依赖，可能破坏go.sum校验 - 拒绝
go get github.com/gofiber/fiber/v3——v3 尚未发布正式版（截至 2026 年 10 月），文档、CI 工具链和生态中间件均未对齐
go mod tidy 后检查 go.mod 是否干净
执行 go mod tidy 后，打开 go.mod 文件，重点核对三处：
- 首行
module名称是否是你项目的真实路径（不是example.com占位符） - 是否有意外引入的
replace或exclude行（Fiber v2 不需要任何替换） -
require区块中是否只有类似这样的行：github.com/gofiber/fiber/v2 v2.52.0（版本号应为 v2.x，不含+incompatible）
如果出现 github.com/gofiber/fiber v1.14.6（无 /v2）或 github.com/gofiber/fiber/v2 v2.52.0+incompatible，说明之前执行过错误命令，需手动删掉该行，再重新 go get github.com/gofiber/fiber/v2。
初始化代码里别用 fiber.Default()
哪怕只是临时跑 demo，也建议从 fiber.New() 开始。因为 fiber.Default() 会隐式启用 Logger、Recover、RequestID 三个中间件，一旦你后续加了 go mod tidy，go.sum 会多出一堆日志/trace 相关依赖（如 github.com/valyala/fasthttp 的特定 commit），这些不是 Fiber 核心所需，反而增加构建体积和兼容风险。
最小可用示例应长这样：
package main
import "github.com/gofiber/fiber/v2"
func main() {
app := fiber.New() // 不是 fiber.Default()
app.Get("/", func(c *fiber.Ctx) error {
return c.SendString("ok")
})
app.Listen(":3000")
}
这个结构下 go mod tidy 生成的 go.mod 最精简，后续加中间件（比如 logger.New()）时，依赖才按需引入。
