kratos new 是唯一可靠方式,执行前须校验 protoc≥3.21、protoc-gen-go=v1.31、GO111MODULE=on 且 GOPROXY 已配置;否则项目骨架不可运行,错误常静默出现。

直接用 kratos new 初始化,别手建目录、改 go.mod 或复制配置——这是唯一可靠起点,其他方式大概率导致 wire.go 缺失、conf.pb.go 生成失败或 config.yaml 加载 panic。
kratos new 前必须确认的三件事
很多人在执行 kratos new helloworld 后得到空文件夹或报错,根源就在这三项没对齐:
-
protoc ≥ 3.21且protoc-gen-go = v1.31(不是最新版!v1.32+会因google.golang.org/protobuf接口变更导致api/下的.pb.go文件生成失败) -
GO111MODULE=on未启用:Kratos 强依赖模块化,关闭时go mod download会漏掉google.golang.org/grpc/cmd/protoc-gen-go-grpc等关键工具 -
GOPROXY不可用:国内环境若没设为https://goproxy.cn,direct,kratos new会在拉取模板时卡死在github.com/go-kratos/kratos-layout,超时后静默失败
生成后立刻验证的两个关键点
项目目录生成完成 ≠ 可运行。常见“本地跑不起来”问题,基本都出在这两处没检查:
- 确认
internal/conf/conf.proto存在,且已被internal/conf/conf.pb.go正确引用:缺失会导致conf.Load()panic 报错"unknown field 'xxx' in conf.Config" - 检查
cmd/helloworld/wire.go中是否已声明InitializeApp函数:这是 Wire 依赖注入的入口,若被误删或未生成,kratos run会报"undefined: InitializeApp"
go generate ./ 和 kratos run 的实际作用
go generate ./ 不是可选步骤,它负责生成三类关键产物:
-
api/下所有.pb.go、_grpc.pb.go、_http.pb.go文件(基于.proto) -
internal/conf/conf.pb.go(基于conf.proto,用于结构化加载configs/config.yaml) -
cmd/helloworld/wire_gen.go(基于wire.go,实现依赖注入图)
kratos run 本质是调用 go run ./cmd/helloworld,但会自动加载 configs/config.yaml 并启动 gRPC(默认 :9000)和 HTTP(默认 :8000)服务。如果 go generate 没跑,wire_gen.go 就不存在,kratos run 必然失败。
最易被忽略的是:所有生成逻辑都强耦合于 kratos new 创建的模板结构。哪怕只是手动删掉一个 conf.proto 字段、改错 package 名,后续 go generate 都可能静默跳过某些文件,而错误只在运行时暴露为配置字段未初始化或 service 注入 nil 指针。











