kratos upgrade仅更新CLI工具，项目依赖须手动升级：执行go get -u github.com/go-kratos/kratos/v2@latest等命令，并确保protoc≥3.21、protoc-gen-go=v1.31.x；升级后需验证conf.proto与config.yaml字段一致、wire.go含InitializeApp声明。
你需要将 Kratos 项目中已过时的框架依赖（如 kratos/v2、contrib 模块、wire、protoc-gen-go 等）升级到兼容当前 Go 版本和协议规范的新版本，避免因 protoc 接口变更、protobuf 升级或 wire 注入失败导致 kratos run 启动报错或 make api 生成失败。
确认当前项目所用 Kratos 主版本与依赖状态
进入项目根目录，执行：
go list -m github.com/go-kratos/kratos/v2
若输出类似 github.com/go-kratos/kratos/v2 v2.11.0，说明使用的是 v2 分支；若为 v3.0.0-xxx 或无 /v2 后缀，则可能已切到 v3 预发布分支——【v2 与 v3 不兼容，不可混用】。检查 go.mod 中是否含 replace github.com/go-kratos/kratos/v2 => ../kratos 这类本地路径替换，有则需先清理，否则 upgrade 命令无效。
执行 kratos upgrade 更新 CLI 工具自身
这一步只更新你本地安装的 kratos 命令行工具，不改动项目代码：
kratos upgrade
该命令等价于 go install github.com/go-kratos/kratos/cmd/kratos/v2@latest，会拉取最新稳定版并覆盖 $GOPATH/bin/kratos。升级后验证：
kratos version → 输出应为 v2.12.0 或更高（截至 2026 年 10 月最新稳定版为 v2.12.1）。
更新项目内 Kratos 框架及配套模块
kratos upgrade 不会修改你的项目依赖，必须手动操作：
方法一：使用 go get 批量升级核心模块
go get -u github.com/go-kratos/kratos/v2@latest
go get -u github.com/google/wire/cmd/wire@latest
go get -u google.golang.org/protobuf@latest
go get -u google.golang.org/grpc@latest
方法二：精准指定版本（推荐用于生产环境）
先查最新兼容版本：
curl -s "https://api.github.com/repos/go-kratos/kratos/releases/latest" | grep tag_name
得到 v2.12.1 后，执行：
go get github.com/go-kratos/kratos/v2@v2.12.1
go get github.com/go-kratos/kratos/contrib/config/polaris/v3@v3.0.4
go get github.com/google/wire/cmd/wire@v0.5.0
【注意：contrib 模块版本号与主框架不一致，必须单独查其 release 页面确认，例如 polaris/v3 当前最新为 v3.0.4】
方法三：强制同步 go.mod（适用于依赖混乱后修复）
go mod tidy -compat=1.21
该命令会清除未引用的依赖、补全缺失项，并按 Go 1.21 兼容性重排 require 顺序。执行后检查 go.mod 中 go 1.21 是否存在，缺失则手动添加。
验证升级结果并修复常见断裂点
第一步：检查 proto 生成链是否通畅
protoc --version → 必须 ≥ 3.21
protoc-gen-go --version → 必须为 v1.31.x（不是 v1.32+！）
若版本超标，需降级：
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.31.0
第二步：重新生成 API 与注入代码
make api → 确保 api/*.pb.go 正常生成且无 import 错误
make wire → 检查 wire_gen.go 是否更新，若报 "cannot find module providing package github.com/go-kratos/kratos/v2"，说明 replace 未清除干净，删掉 go.mod 中所有 replace 行再试。
第三步：启动验证
kratos run → 观察日志中是否出现 config.Load() panic 或 InitializeApp undefined。前者代表 conf.proto 结构与 configs/config.yaml 字段不匹配，需同步更新配置文件；后者代表 wire.go 中入口函数被破坏，应从 kratos new 新项目中复制标准 InitializeApp 声明。
