Go微服务开发环境必须闭环：需安装protoc及插件、匹配版本的goctl、Nacos或etcd注册中心，并正确配置go mod与GOPROXY，缺一不可。
Go 微服务项目开发环境不是装完 Go 就能跑起来的，缺 protoc、goctl、Nacos 或 etcd 任一环，goctl api go 或 goctl rpc proto 都会直接报错退出——这不是配置问题，是工具链根本没闭环。
protoc 和 gRPC 插件必须本地可执行
很多团队把 protoc 当成“写完再装”的东西，结果第一次生成代码就卡在 protoc: command not found。go-zero 的 goctl 依赖 protoc 做解析，且必须搭配 protoc-gen-go 和 protoc-gen-go-grpc 才能产出可用的 gRPC stub。
- Linux/macOS：用
brew install protobuf（macOS）或apt install protobuf-compiler（Ubuntu），再go install google.golang.org/protobuf/cmd/protoc-gen-go@latest和go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest - Windows：下载
protoc-21.12-win64.zip解压后把bin/protoc.exe加入 PATH；插件必须用go install安装，不能靠go get（后者在 Go 1.17+ 已弃用） - 验证方式：运行
protoc --version和protoc-gen-go --version，两者都得有输出；若提示permission denied，检查文件是否被系统标记为“来自互联网”，macOS 需右键“打开”，Windows 需手动解除锁定
goctl 必须与 go-zero 版本对齐
goctl 不是通用代码生成器，它和你项目中 github.com/zeromicro/go-zero 的 commit 或 tag 强绑定。用 @latest 安装，很可能生成的代码调用不存在的方法，比如 svcCtx.Transformer 报错——因为新版本删了这个字段，但旧版 go-zero 还在用。
- 查项目里 go.mod 中 go-zero 的版本，例如
github.com/zeromicro/go-zero v1.7.5，就用go install github.com/zeromicro/go-zero/tools/goctl@v1.7.5 - 别在 GOPATH 下装；goctl 二进制默认落在
$GOBIN（通常是$HOME/go/bin），确保该路径在 PATH 中 - 常见错误：
goctl api go -api app.api -dir .报undefined: zrpc.Client，大概率是 goctl 版本高于项目依赖的 go-zero
Nacos / etcd 服务发现组件要提前跑通
go-zero 的 zrpc 和 rest 模块默认启用服务发现，哪怕只是本地调试，也得有一个注册中心响应心跳。不启动 Nacos 或 etcd，服务一启动就 panic 在 registry: failed to register，而不是安静地降级为直连。
立即学习“go语言免费学习笔记（深入）”；
- 推荐用 Docker 快速拉起：Nacos 用
docker run -d -p 8848:8848 --name nacos -e MODE=standalone nacos/nacos-server:v2.3.2；etcd 用docker run -d -p 2379:2379 --name etcd quay.io/coreos/etcd:v3.5.10 etcd -advertise-client-urls http://0.0.0.0:2379 -listen-client-urls http://0.0.0.0:2379 - 检查连通性：curl
http://localhost:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=10应返回 JSON；或etcdctl --endpoints=localhost:2379 endpoint health - 配置里别写
127.0.0.1：Docker 容器内访问宿主机要用host.docker.internal（macOS/Windows）或宿主机真实 IP（Linux），否则服务注册进去但其他容器找不到
go mod 初始化和 GOPROXY 必须设对
微服务项目通常含多个 module（如 api-gateway、user-rpc、common），每个目录下都要有独立的 go.mod。如果只在根目录 init，子服务 import 公共包时会报 cannot find module providing package。
- 进每个服务目录，运行
go mod init your-domain.com/project/api-gateway（路径要唯一，不能全用main） - GOPROXY 必须显式设置：国内不用
export GOPROXY=https://goproxy.cn,direct，go mod download会卡死或拉错 checksum；验证用go env GOPROXY - 注意
replace的写法：本地调试 common 包时，用replace your-domain.com/project/common => ../common，路径是相对于当前go.mod文件的位置，不是项目根目录
真正卡住人的从来不是某个命令不会敲，而是错误信息指向 A，实际根因在 B——比如 goctl rpc proto 失败，你以为是 proto 文件语法错，其实是 protoc-gen-go-grpc 版本太低不支持 service Foo { rpc Bar(...) returns (...) } 的新写法。工具链每个环节都得亲手验过，才算搭完环境。
