go-zero中rpc启动失败、jwt鉴权失效、api返回空json及goctl编译报错的四大常见问题：1. etcd未运行或配置错误；2. authmiddleware未注册或jwt配置不匹配；3. 响应结构体字段未导出（首字母小写）；4. goctl与go-zero版本不一致。
go-zero 中 rpc 服务启动失败：找不到 etcd 或连接超时
常见现象是日志里反复出现 context deadline exceeded 或 no available endpoint，服务卡在启动阶段。本质不是代码写错了，而是 go-zero 默认依赖 etcd 做服务发现，但本地没跑起来，或配置地址不对。
-
etcd必须提前运行，推荐用 Docker 启动：docker run -d -p 2379:2379 --name etcd quay.io/coreos/etcd:v3.5.15 --advertise-client-urls http://0.0.0.0:2379 --listen-client-urls http://0.0.0.0:2379 -
rpc服务的etc/<service>.yaml</service>里，etcd配置项必须显式指定，不能只靠默认值：etcd:<br> host: 127.0.0.1:2379
- 如果只是本地调试不想依赖
etcd，可以临时改用直连模式：把conf.MustLoad换成手动构造config.Config，跳过etcd初始化，但上线前必须切回去
go-zero 的 jwt 鉴权不生效：用户能绕过 AuthMiddleware
最常见原因是中间件没注册进路由链，或者 jwt 配置路径写错。它不会报错，只是静默跳过验证。
-
jwt秘钥（SigningKey）必须和前端传来的 token 签名算法一致；go-zero默认用HS256，别误配成RS256 - 中间件要显式挂载到每个需要鉴权的路由组，比如：
server.AddRoute(rest.Route{Method: http.MethodGet, Path: "/user", Handler: handler.UserHandler, Middlewares: []rest.Middleware{middleware.AuthMiddleware(jwt.NewJwtAuthenticator(conf.JwtConf))}}) - 检查请求头是否带了
Authorization: Bearer <token></token>——go-zero默认只认这个格式，不支持X-Token或其他自定义 header
go-zero 生成的 api 服务返回空 JSON：{} 而不是预期字段
这不是序列化问题，而是结构体字段没导出。Go 的 JSON 编码器只会序列化首字母大写的公开字段，小写字段直接忽略。
- 检查你的响应结构体，比如：
type UserResp struct { name string `json:"name"` }→ 这个name永远不会出现在 JSON 里，必须改成Name string `json:"name"` - 如果用了
goctl api go自动生成代码，确保.api文件里字段定义首字母大写，例如string name应写为string Name - 注意嵌套结构体同理，哪怕外层导出了，内层字段没导出照样为空
go-zero 项目里 goctl 生成的代码编译报错：undefined: xxx
通常是 goctl 版本和框架版本不匹配，尤其是 v1.4.x 和 v1.5.x 之间有大量内部函数签名变更，生成的代码会调用不存在的方法。
- 先查当前
go-zero版本：grep 'github.com/zeromicro/go-zero' go.mod，再查goctl版本：goctl -v - 必须让两者 major 版本一致，比如
go-zero v1.5.4就得用goctl v1.5.4，别混用v1.4.x的二进制 - 升级
goctl不要用go install直接拉 master，而要用对应 tag：GO111MODULE=on go install github.com/zeromicro/go-zero/tools/goctl@v1.5.4
所有这些环节里，etcd 地址、结构体大小写、goctl 版本这三处最容易被跳过检查，一卡就是半天
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
