goctl生成代码前必须验证语法并确保配置路径、环境变量和目录结构一致，否则易导致panic、unimplemented错误或配置加载失败。
能快速开发、也能快速部署，前提是别把 goctl 当成摆设，也别跳过配置隔离这步——否则本地跑通的 service，上线后大概率连不上 Nacos 或读错 config。
goctl 生成代码前必须确认 proto 和 api 文件语法合法
很多报错其实不是框架问题，而是 goctl 解析失败后静默跳过，生成的代码缺字段、少方法，运行时 panic 或 gRPC 调用直接返回 UNIMPLEMENTED。
- proto 文件里
option go_package必须和实际目录结构一致，比如写成./account，那生成代码就得放在proto/account/下，不能扔进rpc/service/ - api 文件中
@server块里的middleware名称要和实际注册的中间件变量名完全匹配，大小写敏感，AuthInterceptor写成authinterceptor就不会生效 - 运行
goctl api go -api xxx.api -dir .前，先用goctl api validate -api xxx.api检查语法，它比编译报错早暴露问题
服务启动时 config.yaml 的环境变量覆盖容易失效
go-zero 默认用 conf.MustLoad 加载配置，但如果你依赖 os.Getenv 动态替换字段（比如数据库密码），而没在 config.yaml 里显式声明占位符，就会 fallback 到空字符串或默认值，导致连接拒绝。
- config.yaml 中所有可变字段（如
DataSource、Etcd.Endpoints）必须写成${DB_SOURCE}这种格式，不能靠代码里手动os.Getenv拼接 - 启动命令要带
env参数：DB_SOURCE="root:pass@tcp(10.0.1.2:3306)/test" ./service，go-zero 会自动注入 - Nacos 配置中心启用后，本地
config.yaml会被远程配置完全覆盖——测试阶段建议先关掉Nacos配置块，验证基础逻辑
Docker 镜像构建时工作目录和配置路径不匹配
goctl 生成的 Dockerfile 默认把 config 放在 /app/config，但服务启动时如果没指定 -f 参数，默认只找当前目录下的 config.yaml，容器里就找不到配置文件，直接 panic。
- 启动命令必须显式指定配置路径：
./service -f /app/config/config.yaml - 若用 Kustomize 或 Helm，确保
volumeMounts挂载路径和代码里conf.MustLoad的路径一致，常见错误是挂载到/etc/config却还在读./config.yaml - 镜像里不要保留
go.mod和proto目录，它们只在构建期需要；最终镜像应只含二进制和/app/config
goctl kube deploy 生成的 YAML 缺少 readinessProbe
自动生成的 Kubernetes Deployment 默认没加就绪探针，K8s 会把流量导给还没初始化完的 Pod，导致 503 或超时——尤其当服务依赖 Nacos 注册、MySQL 连接池预热时，冷启动可能要 3~5 秒。
- 手动补上
readinessProbe，路径用 go-zero 默认的健康检查端点：/health，初始延迟设为10秒，间隔5秒 - 如果用了自定义路由前缀（比如
@server(prefix: /v1)），健康检查路径也要同步改成/v1/health -
goctl kube deploy输出的 YAML 是起点，不是终点；务必检查env、resources、livenessProbe是否符合生产要求
真正卡住人的从来不是“怎么生成”，而是生成后的路径、权限、环境变量三者对不上——多花两分钟核对 goctl 输出的目录结构、Dockerfile COPY 行、以及运行时 -f 参数，比重启五次 Pod 更省时间。
