要在Windows或macOS上运行go-zero微服务项目，必须安装Go环境（≥1.20且GO111MODULE=on）、protoc及gRPC插件、与go-zero版本匹配的goctl、以及Nacos/etcd注册中心，缺一不可。
要在 Windows 或 macOS 上真正跑起一个 go-zero 微服务项目，光装 Go 语言环境远远不够——缺 protoc、缺匹配版本的 goctl、缺注册中心（Nacos/etcd），任意一环缺失都会导致 goctl api go 或 goctl rpc proto 直接报错退出，连第一行代码都生成不了。
确认 Go 环境并启用模块
打开终端（Windows 用 PowerShell 或 CMD，macOS 用 Terminal），执行：
go version
必须看到类似 go version go1.22.1 windows/amd64 或 go version go1.22.1 darwin/arm64 的输出。低于 1.20 的版本建议升级，go-zero v1.7+ 已不兼容 1.19 及更早版本。
运行以下命令确保 Go Module 已开启：
go env GO111MODULE
若输出不是 on，立即执行：
go env -w GO111MODULE="on"
【GO111MODULE 必须为 on，否则 goctl 生成的依赖路径会错乱，后续 mod tidy 会失败】
安装 protoc 及 gRPC 插件
protoc 是 go-zero 代码生成的底层依赖，不是可选工具——没有它，goctl rpc proto 会直接提示 protoc: command not found 并终止。
方法一（macOS，推荐用 Homebrew）：
brew install protobuf
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（官方 release 页面可得），解压后将 bin/protoc.exe 所在目录加入系统环境变量 Path；
然后在 PowerShell 中执行：
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
验证是否成功（两行命令都必须有版本输出）：
protoc --version
protoc-gen-go --version
若提示 permission denied：macOS 需右键 → “显示简介” → 勾选“仍要打开”；Windows 需右键 protoc.exe → 属性 → 勾选“解除锁定”。
安装与项目匹配的 goctl
goctl 不是通用工具，它和你项目中 go.mod 里引用的 go-zero 版本强绑定。用 @latest 安装，大概率生成调用已删除字段（如 svcCtx.Transformer）的代码，编译直接报错。
第一步：进入你的项目根目录，查看 go.mod 中 go-zero 版本：
grep "github.com/zeromicro/go-zero" go.mod
假设输出为：
github.com/zeromicro/go-zero v1.7.5
第二步：执行精准安装：
go install github.com/zeromicro/go-zero/tools/goctl@v1.7.5
第三步：确认安装路径在 PATH 中：
echo $PATH（macOS/Linux）或 echo %PATH%（Windows），检查是否含 $HOME/go/bin 或 %GOPATH%\bin
第四步：验证：
goctl -v
如果提示 command not found：macOS/Linux 检查 ~/.zshrc 或 ~/.bash_profile 是否添加了 export PATH=$PATH:$HOME/go/bin；Windows 检查系统环境变量 Path 是否包含 %GOPATH%\bin。
启动注册中心（Nacos 或 etcd）
go-zero 的 zrpc 和 rest 模块默认启用服务发现。哪怕只做本地调试，也必须有一个注册中心响应心跳——不启动 Nacos 或 etcd，服务一运行就 panic 在 registry: failed to register，不会静默降级。
方法一（Docker 快启 etcd，推荐）：
docker run -d --name etcd -p 2379:2379 -e ETCD_ENABLE_V2=true quay.io/coreos/etcd:v3.5.0
方法二（Nacos 单机模式）：
下载 nacos-server-2.3.2.zip，解压后进入 bin 目录：
Windows：双击 startup.cmd -m standalone
macOS/Linux：执行 sh startup.sh -m standalone
启动后访问：
etcd：无需 Web 访问，go-zero 服务启动时自动连接 localhost:2379
Nacos：浏览器打开 http://localhost:8848/nacos，默认账号密码均为 nacos
【注册中心端口必须开放且无防火墙拦截，Windows 用户需确认 Hyper-V 或 WSL2 已启用，否则 Docker 容器无法正常通信】
