kratos 官方的「从 v2 迁移到 v3」说明里，把升级边界讲得非常直白：v3 直接升级了 module 主版本，切换到标准库的 `log/slog`，把所有可选依赖从 core 核心包里移出，还删掉了公开的 http binding 包。官方特意提醒，别以为直接把代码里的 `/v2` 批量替换成 `/v3` 就完事，这次升级本质是完整的代码迁移，改完得重新生成相关代码，跑完所有集成测试才算完成。
来源：Kratos 官方文档
迁移对照表最醒目的变化是版本基线调整：v2.9.2 最高适配 Go 1.22，v3.0.0 最低要求 Go 1.25。官方建议动手修改 module 前，先把环境升级到 v3 支持的 Go 版本，本地开发环境、CI 镜像、Docker 构建镜像、代码检查工具、代码生成任务全部同步更新。企业级项目走这一步时，影响的是整条流水线和基础镜像，远不止开发机上敲一条 `go get` 命令那么简单。
来源：Kratos 官方文档
日志体系的改动是实打实的工作量。v3 的应用入口和中间件配置项现在直接接收 `*slog.Logger` 类型，原来 v2 里用的 log.Logger、log.Helper、log.Valuer、log.NewStdLogger，还有 helper 自带的 trace、service 这类字段，全都得替换掉。之前接入了第三方 Kratos 日志适配器的项目，得先确认第三方有没有提供适配 slog.Handler 的版本，没有的话就得自己维护一层适配层。
JSON 编解码和可选中间件也得逐个逐项处理。v3 的核心包里默认注册了 Go 原生 JSON 和 protobuf JSON 两个明确的编解码器，要是想保留 v2 时期的混合 JSON 兼容行为，得单独引入 contrib 模块的对应实现。JWT、指标上报、链路追踪这些能力现在都拆到了独立的 contrib 模块里，应用得自己管理 OpenTelemetry 的 provider、exporter、资源配置、采样策略和关闭逻辑。这些内容官方迁移页全列了出来，都要走搜索替换、重新生成代码、测试的完整流程。
官方设计理念页也给迁移工作定了判断依据：Kratos 本身就是用 Go 搭建服务的工具箱，按需选用需要的组件，全程由开发者自己把控项目架构和底层基础设施。v3 虽然更新了所有公开 API 和工具链，但核心思路没变：保持小接口、显式组装逻辑、自动生成 transport 适配器、所有底层组件都可替换。也就是说这次迁移根本不需要动业务层代码，优先处理框架接口、生成代码、日志、编解码器和中间件的集成方式就好。
官方迁移页最后附了一份部署检查清单，覆盖 Go 版本校验、core 与 contrib 导入路径修正、日志构造逻辑、JSON 契约测试、JWT 与 OpenTelemetry 配置、HTTP binding 导入路径、代码重生成结果、预发布环境验证这几项。跑生产服务的话，这些检查点比单独跑个 Demo 能不能启动重要多了：只有调用方逻辑、路由规则、错误返回、服务发现名称、JSON 语义全部保持兼容，v2 和 v3 的实例混部的时候才足够可控。
信源说明：本文内容全部整理自 Kratos 官方 v2 到 v3 迁移文档和设计理念页面，实际升级前一定要以你自己项目里的导包情况、生成代码、CI 工具链、HTTP/gRPC 契约测试和预发布环境验证结果为准。
