kratos new是唯一可靠的项目初始化方式,必须预先校验protoc≥3.21、protoc-gen-go=v1.31、GO111MODULE=on且GOPROXY已配置;生成后须确认internal/conf/conf.proto与conf.pb.go包路径一致,以及cmd/server/wire.go中存在InitializeApp函数。

kratos new 是唯一能用的初始化方式
别试 blades new、别 clone 模板仓库、别手动建目录。Kratos 的 proto → pb.go → wire.go → config.yaml 四者强绑定,绕过 kratos new 就等于破坏契约起点。国内网络下 blades new 常卡在 “template not found: kratos-layout”,且无 fallback;而 kratos new 自带本地缓存(存于 $HOME/.kratos/repo/),首次成功后,后续新建秒级完成。
执行前必须校验的三个环境项
不满足任一条件,生成的项目骨架不可运行,错误常静默出现(比如只建了个空目录):
-
protoc --version必须 ≥ 3.21;低于此版本会导致api/下的.pb.go文件缺失字段,后续kratos run报"undefined: xxxRequest" -
protoc-gen-go必须是 v1.31(不是 v1.32+);新版因google.golang.org/protobuf接口变更,会跳过生成,只留下空的conf.pb.go -
GO111MODULE=on且GOPROXY已设(推荐https://goproxy.cn);国内未设代理时,kratos new在拉取模板时超时,无报错、无提示、只生成空文件夹
生成后立刻验证的两个关键文件
项目目录建出来 ≠ 能跑。90% 的首次启动失败,都卡在这两处没检查:
- 确认
internal/conf/conf.proto存在,且其go_package声明与生成的internal/conf/conf.pb.go包路径一致;否则conf.Load()会 panic,报错"unknown field 'xxx' in conf.Config" - 打开
cmd/server/wire.go,确认存在func InitializeApp();这是 Wire 依赖注入的入口函数,若被删或未生成,kratos run直接报"undefined: InitializeApp",而非配置类提示
第一次 kratos run 失败最常卡在路径和模块上
常见现象是报 "failed to load config" 或找不到 wire.go:
- 务必在项目根目录执行
kratos run,不要进到cmd/server下运行;它需要读取configs/config.yaml和顶层wire.go - 执行
go mod tidy再跑;官方模板的go.mod可能与你本地 Go 1.21+ 不兼容,tidy会自动修正依赖版本 - 别手动删
go.mod后重写——kratos new生成的模块声明已适配框架契约,改它大概率触发 wire 注入链断裂
真正容易被忽略的是:所有校验必须在 kratos new 执行前完成,而不是等报错后再回头查。工具链版本错配导致的失败,往往没有明确错误信息,只有空目录、空文件或 panic 前的静默中断。











