kratos new 项目跑不起来的主因是环境链路断裂：模板拉取超时（推荐换 Gitee 镜像）、protoc 及插件未装全或不在 PATH、go.mod 版本不匹配、go generate 未执行或未在根目录执行、HTTP 路由路径错误或端口被占。
直接上手 Kratos 微服务开发，不需要先搞懂所有概念——只要按顺序执行这三步：装好工具链、生成项目、跑通第一个接口。跳过任何一步都可能卡在 kratos run 报错或 go generate 失败。
kratos new 生成项目时为什么卡住或报错？
常见现象是命令长时间无响应、提示 failed to clone repo 或生成的目录里缺 api/ 和 internal/。本质是模板拉取失败，不是你本地 Go 环境问题。
- 默认模板地址是
https://github.com/go-kratos/kratos-layout.git，国内访问慢或被限，优先换 Gitee 镜像：kratos new helloworld -r https://gitee.com/go-kratos/kratos-layout.git - 如果仍失败，手动克隆模板到
$HOME/.kratos/repo并重试；不要删go.mod再go init，新版 Kratos 依赖声明已收敛，改了反而触发wire初始化失败 - 生成后检查
api/helloworld/v1/greeter.proto是否存在，缺失说明模板没完整解压，删掉项目重来
go generate . 执行失败的几个硬性前提
go generate 不是可选步骤，它负责生成 .pb.go、conf.pb.go、wire_gen.go —— 缺一个，kratos run 就会 panic。
- 必须提前安装
protoc（v3.21+）和两个插件：protoc-gen-go、protoc-gen-go-grpc；仅go install不够，还要确保它们在$PATH里，运行protoc-gen-go --version能输出版本号 -
go.mod里的go版本声明要 ≥ 1.21，否则wire生成失败，错误信息类似unknown directive: go - 别在子目录里执行
go generate，必须在项目根目录（即含go.mod的那层）执行
kratos run 启动后 curl 404 或连接拒绝？
成功启动日志里一定有两行：[gRPC] server listening on: [::]:9000 和 [HTTP] server listening on: [::]:8000。如果只有其中一行，说明对应协议没启用或端口被占。
- 默认 HTTP 路由绑定在
GET /helloworld/kratos，用curl http://127.0.0.1:8000/helloworld/kratos测试，不是/api/hello或其他路径 - 如果提示
connection refused，先lsof -i :8000（macOS/Linux）或netstat -ano | findstr :8000（Windows）看端口是否被占用 - 修改配置前先确认
configs/config.yaml里http.addr和grpc.addr没被注释，且值是":8000"和":9000"，别写成"localhost:8000"（IPv6 场景下不兼容）
最易忽略的是 go generate 之后没重新 go build 就直接 kratos run —— 它内部调用的是当前目录下的 ./bin/helloworld，而这个二进制文件不会自动重建。每次改完 proto 或 wire，都要手动 go build -o ./bin/ . 再跑。
