根本原因是未正确放置和编写.api文件，导致goctl生成的handler、logic、types为空包，svc.ServiceContext中userModel等依赖为nil而引发panic；.api文件须置于api/目录下、含type声明、UTF-8无BOM编码，且goctl命令路径需严格匹配。
goctl 生成的项目一启动就 panic nil pointer 怎么办
根本不是框架 bug，而是 .api 文件没放对位置、内容不合规，导致生成的 types、logic、handler 全是空包，svc.ServiceContext 里注入的 userModel 等依赖自然为 nil。
-
.api文件必须放在api/目录下，例如api/user.api；执行命令时路径要完全匹配：goctl api go -api api/user.api -dir . -
user.api至少得有type声明（定义请求/响应结构体），否则types包为空，后续所有引用都会崩 - 文件编码必须是 UTF-8 无 BOM —— Windows 记事本默认带 BOM，推荐用 VS Code 或 Goland 编辑并手动设编码
- 检查
internal/handler中 handler 初始化是否传入了非空svc.ServiceContext；这个 context 必须在main.go里构造并传入
conf.Load 配置没生效，Port 始终是 0 怎么排查
go-zero 不会自动扫描或热加载配置，conf.Load 是唯一入口，且字段 tag 和 YAML 键名必须严格一致 —— 差一个字母、多一个空格，整个字段就是零值。
- 在
main.go最开头调用conf.MustLoad("etc/user.yaml", &c)，别漏掉&c的取地址符 - YAML 中的 key 名必须和 struct tag 完全一致：比如
Port int `json:"port"`对应 YAML 里的port: 8080，写成Port或PORT都不生效 - 嵌套结构体要用
.分隔，如Database.Host对应 YAML 中database:下一级的host: - 如果用了 Etcd 配置中心，确保
registry字段类型是etcd，且Etcd结构体的 tag 写对了，否则 client 初始化失败
RPC 第一次调用特别慢，之后又正常是为什么
这是 go-zero 的 rpcxclient 懒加载机制导致的阻塞，不是网络问题，也不是服务端响应慢 —— 首次调用才建立连接池，DNS 解析、TCP 握手、TLS 协商过程本身就要几百毫秒甚至更久。
- 别在关键路径上做首次 RPC 调用（比如登录接口里第一次查用户权限）
- 启动时主动预热：在
main()末尾加一段 dummy 调用，触发 client 初始化 - 确认
rpcxclient的Timeout设置合理（默认 2s），避免超时掩盖真实延迟 - 如果用的是 etcd 服务发现，首次建连还包含 watch etcd key 的开销，建议提前注册好服务再启 client
goroutine 泄漏导致内存持续上涨怎么定位
goroutine 不退出、channel 不关闭、timer 不 stop，都可能让 goroutine 卡在阻塞状态长期存活 —— 这类泄漏不会立刻 panic，但会缓慢吃光内存。
立即学习“go语言免费学习笔记（深入）”；
- 用
curl http://localhost:6060/debug/pprof/goroutine?debug=2抓当前全部 goroutine 栈，重点关注卡在select、chan receive、time.Sleep的数量 - 检查所有
go func() { ... }()是否都有明确退出条件，尤其是监听 channel 的循环 - 用
context.WithTimeout或context.WithCancel控制 goroutine 生命周期，别裸写go - 数据库查询、HTTP 调用等外部依赖，必须设超时；没设 timeout 的
http.Client或sql.DB查询容易卡死 goroutine
.api 文件的编码格式和 conf.Load 的取地址符 —— 这两个地方出错，服务根本起不来，但错误日志里只报 nil pointer，容易往框架或业务逻辑上瞎查。 
