kratos new 生成的项目默认不能直接 kratos run 启动，根本原因是初始化链路收紧：kratos 命令未全局安装或版本不匹配、go.mod 未就位、proto 未编译生成、HTTP 路由未在 http.go 中注册，四者缺一不可。
kratos new 生成的项目默认不能直接 kratos run 启动，根本原因不是框架问题，而是初始化链路在 v3 中已收紧：命令未安装、go.mod 未就位、proto 编译缺失、HTTP 路由未注册这四步缺一不可。
kratos 命令必须全局可用且版本匹配 v3
v3 的 kratos CLI 不再兼容旧版模板，必须用 go install 显式安装最新稳定版。执行 which kratos 无输出或提示 version
- 运行
go install github.com/go-kratos/kratos/cmd/kratos/v3@latest（注意末尾/v3） - 确认
$GOPATH/bin已加入$PATH，macOS/Linux 检查~/.bashrc或~/.zshrc，Windows 检查系统环境变量 - v3 CLI 默认拉取的是
kratos-layoutv3 模板，国内建议加-r https://gitee.com/go-kratos/kratos-layout.git避免超时
go.mod 必须手动 init 并指定 Go 版本
v3 模板不再自动生成 go.mod，且要求 Go ≥ 1.21。直接 kratos new demo 后进目录跑 go mod tidy 会失败，因为模块路径为空、Go 版本不匹配。
- 进入项目根目录后，立即执行
go mod init demo（模块名需与项目名一致） - 检查
go.mod第一行是否为go 1.21或更高；若为go 1.16等旧版本，手动改掉 - 运行
go mod tidy，确保github.com/go-kratos/kratos/v3出现在依赖中，而非v2或无版本
proto 编译失败的三个硬性条件
make api 报错 90% 是因为路径、插件、语法三者之一不满足。v3 强制要求 proto 文件放在 api/ 下，且必须用 v3 插件链。
-
.proto文件必须放在api/xxx/v1/目录下，package 声明为package api.xxx.v1; - 必须同时安装两个插件：
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest和go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v3@latest（注意/v3） - 字段类型禁用
float，只允许float32或float64；syntax = "proto3";必须顶格写，前面不能有空格或注释
HTTP 接口 404 但 gRPC 可连的定位点
v3 默认仍复用同一端口（如 8000），但 HTTP 路由注册完全手动，不会自动扫描。curl 返回 404 说明 RegisterXXXHTTPServer 没被调用或函数不存在。
- 确认
internal/server/http.go中显式调用了v1.RegisterUserHTTPServer（函数名取决于你的 proto service 名） - 检查
api/xxx/v1/xxx_http.pb.go是否存在；若缺失，说明make api没成功，或 proto 路径/插件不对 - HTTP 路径前缀由
option (google.api.http)控制，默认是/v1，例如curl http://localhost:8000/v1/users，不是/users
v3 的初始化不是“一键生成即运行”，而是把控制权交还给开发者：每个环节都暴露出来，避免隐式行为掩盖真实依赖。最容易被跳过的其实是 go mod init 和 protoc-gen-go-http/v3 插件——这两个漏掉，后续所有步骤都会卡死，且错误信息往往不指向根源。
