根本原因是未提前编写并正确放置.api文件，导致goctl生成的handler、logic、types为空包，svc.servicecontext中依赖（如usermodel）为nil，进而引发panic。
goctl 生成的项目一启动就 panic nil pointer 怎么办
根本原因不是框架有问题，而是 goctl 生成的骨架依赖你提前写好且路径正确的 .api 文件。没这个文件，handler、logic、types 都是空包，svc.ServiceContext 里注入的依赖（比如 userModel）自然为 nil。
常见错误现象：
- 执行
go run user.go报错panic: runtime error: invalid memory address or nil pointer dereference - 日志里看不到任何路由注册信息，
server.Start()前就崩了
实操建议：
-
.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中构造并传入
conf.Load 没生效，配置字段始终是零值
go-zero 不会自动扫描或热加载配置，conf.Load 是唯一入口，且要求结构体字段 tag 与 YAML 键名严格一致。写错一个字母、多一个空格，整个字段就失效。
常见错误现象：
-
etc/user.yaml里写了Port: 8080，但服务始终监听0.0.0.0:0 - 数据库连接字符串明明改了，日志里还是连旧地址
实操建议：
- 在
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 调用第一次很慢，之后又正常
这是 RPC client 懒加载导致的阻塞，不是网络问题，也不是服务端响应慢。go-zero 的 rpcxclient 默认首次调用才建立连接池，而建连过程（DNS 解析、TCP 握手、TLS 协商）需要几百毫秒甚至更久。
实操建议：
- 在服务启动后主动预热一次关键 RPC 调用，比如在
main函数中init阶段调用一次xxxClient.Ping - 避免在 HTTP handler 中首次触发 RPC 调用——这会让首屏延迟不可控
- 若使用 ETCD 注册中心，确认节点列表稳定；频繁变更会导致 Resolver 反复重建连接池
- 生产环境建议开启连接池预热配置（通过
rpcx.ClientOption设置WithPoolSize和WithKeepAlive）
数据库模型生成后查不到数据，但 SQL 日志显示正常
go-zero 的 model 层默认启用缓存，主键查询走的是缓存而非 DB，而缓存未命中时才会回源。如果缓存键构造错误、或字段名大小写不一致，就会查不到数据却无报错。
实操建议：
- 检查
model生成时是否加了-c参数（启用缓存），没加则不会走缓存逻辑 - 确认结构体字段 tag 是否与数据库列名一致，尤其注意大小写：
ID字段 tag 应为json:"id" gorm:"column:id"，否则缓存 key 构造失败 - 临时关闭缓存验证：在 model 方法前加
cache.WithCacheKey("")强制绕过缓存 - 启用 SQL 日志的同时，加一行
logx.Info("cache key:", cacheKey)看 key 是否符合预期
.api 文件的 type 声明完整性，以及配置 struct tag 和 YAML key 的大小写一致性——这两处出错不会报编译错误，但会在运行时静默失效。
