Fiber本地调试报错需分四步排查：先确认Node与Fiber版本兼容（v2.50.0+），再检查app.Listen()位置及端口占用，接着用日志和recover定位中间件panic，最后通过/debug/routes验证路由是否在Listen前注册。
调试Fiber框架本地服务时遇到报错，往往卡在启动失败、路由不生效或中间件崩溃等环节，直接看控制台堆栈容易漏掉关键线索。
确认Fiber版本与Node.js兼容性
打开终端，执行 node -v 查看当前Node版本；再运行 npm list fiber（注意不是 fiber 包，而是 @gofiber/fiber）确认安装的Fiber主包版本。
若 Node 版本为 v18.19.0 或 v20.15.0，但 Fiber 版本低于 v2.50.0，则【必须升级到 v2.50.0+】——旧版对 V8 11.x+ 的 Promise 处理存在竞态 bug，会导致 app.Listen() 后无响应却无报错。
这一步操作起来很简单，直接改 package.json 中 "@gofiber/fiber" 的版本号再 npm install 即可。
检查 app.Listen() 调用位置和端口占用
方法一：在 app.Listen() 前加一行 console.log('Starting server on port 3000...')，观察该日志是否输出。未输出说明执行卡在 Listen 之前，大概率是中间件 panic 或配置校验失败。
方法二：把端口号从 3000 换成 0（即 app.Listen(0)），让系统自动分配空闲端口。如果此时能启动成功，说明原端口被占用——可用 lsof -i :3000（macOS/Linux）或 netstat -ano | findstr :3000（Windows）查进程并 kill。
方法三：在 app.Listen() 后紧跟 console.error，例如：app.Listen(3000).catch(err => console.error('Fatal:', err))。【不加 catch 会静默吞掉底层 net.Server 错误】，这是本地调试最常踩的坑。
定位中间件崩溃的具体位置
第一步：注释掉所有自定义中间件，只保留 app.Use(logger.New()) 和 app.Get("/", func(c *fiber.Ctx) error { return c.SendString("OK") })，确认基础服务能否启动并响应。
第二步：逐个取消注释中间件，每次添加一个后重启服务，直到复现崩溃。重点盯住含异步操作（如 await db.Connect()）、同步阻塞调用（如 fs.readFileSync）或未处理错误的 defer/recover 块。
第三步：对疑似中间件，在入口处加 fmt.Printf("middleware %s start\n", "name")，并在末尾加 fmt.Printf("middleware %s end\n", "name")。若只看到 start 没有 end，说明该中间件内部 panic 且未 recover。
第四步：在 app.Use(func(c *fiber.Ctx) error { ... }) 内部最外层包裹 defer func() { if r := recover(); r != nil { log.Printf("PANIC in middleware: %v", r) } }()，捕获并打印 panic 值。
验证路由注册是否生效
启动服务后，访问 http://localhost:3000/debug/routes（需先启用 github.com/gofiber/fiber/v2/middleware/pprof）查看当前注册的所有路由表。若页面 404，说明 pprof 中间件没挂载；若路由为空，说明 app.Get/Post 等调用发生在 app.Listen() 之后——【Fiber 不支持 Listen 后动态注册路由】，必须确保所有 app.Xxx() 在 app.Listen() 前完成。
这一步不需要额外代码，只需打开浏览器访问即可验证。
