Hertz调试需严格匹配handler签名、正确注册中间件、配置Netpoll传输器并确保GoLand正确解析app.RequestContext类型。
GoLand 调试 Hertz 路由时 handler 函数签名不匹配会直接 panic
Hertz 的路由 handler 必须严格接收两个参数：context.Context 和 *app.RequestContext。GoLand 默认生成的函数签名（比如只带一个 gin.Context 或漏掉 context.Context）会导致服务启动失败，报错类似 cannot use xxx (type func(http.ResponseWriter, *http.Request)) as type app.HandlerFunc。
实操建议：
- 手动补全 handler 签名，别依赖 GoLand 自动补全模板（它默认按 net/http 或 Gin 习惯推导）
- 在
main.go或router.go中注册路由前，先确认 handler 类型是否为func(context.Context, *app.RequestContext) - 用 GoLand 的「Go to Declaration」跳转到
h.GET定义，看其参数类型约束，反向校验 handler 是否满足
断点打在中间件里却没触发？检查中间件注册顺序和嵌套层级
Hertz 中间件是链式包裹执行：越靠前注册的中间件，越早进入、越晚退出。但 GoLand 调试时，如果断点没命中，大概率不是断点失效，而是中间件根本没被调用——常见于路由未命中或中间件注册位置错误。
实操建议：
- 确保中间件在
h.Use(mw1, mw2)中注册，且该调用发生在任何h.GET/h.POST之前 - 不要在分组路由（如
h.Group("/api")）外层注册中间件后，又在子路由里重复Use—— 这会创建两层包裹，可能干扰调试流 - 在中间件函数第一行加
log.Println("hit middleware:", c.Request.URL.Path)辅助验证是否进入，比纯断点更可靠
GoLand 无法解析 app.RequestContext 类型跳转
GoLand 默认索引可能未识别 Hertz 的模块路径，导致 app.RequestContext 显示为 unresolved reference，跳转失败、无代码提示、甚至影响断点绑定。
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
实操建议：
- 检查
go.mod中是否已声明github.com/cloudwego/hertz依赖（v0.9.0+ 推荐），运行go mod tidy后重启 GoLand 索引 - 在 GoLand 设置中打开
Settings > Go > GOROOT and GOPATH，确认 GOPATH 与项目go.work或go.mod路径一致 - 右键项目根目录 →
Reload project，强制刷新 Go 模块解析上下文
调试时请求卡住、超时，其实是 Netpoll 传输器未启用
GoLand 调试模式下，如果看到请求一直 pending、响应迟迟不返回，且日志里没有 HTTP server listening on address，大概率是 server.New() 启动时没指定 Netpoll 传输器，导致底层阻塞在标准库 net/http 的 goroutine 调度上——而 GoLand 的 debugger 对这类调度敏感，容易假死。
实操建议：
- 启动代码必须显式传入
server.WithTransport(netpoll.NewTransporter)，哪怕只是本地调试 - HTTPS 场景除外：此时需换回
standard.NewTransporter，否则 TLS handshake 失败，调试器会卡在连接建立阶段 - 临时绕过 Netpoll 调试可加
-gcflags="-l"编译参数禁用内联，让断点更稳定，但仅限排查逻辑，非性能测试
真正卡住的地方往往不在 handler 里，而在 transport 层初始化或中间件链入口；调试前先确认服务是否真正 listen 成功，比在业务逻辑里反复加断点更省时间。
