kratos项目启动失败的根本原因是环境链路断裂：kratos命令未全局安装、go版本或模块配置不兼容、proto插件缺失或路径错误、http路由未注册、端口冲突等。
Kratos框架新手在执行kratos new或kratos run时频繁遇到项目无法启动、命令未找到、proto编译失败等报错，根本原因不是代码写错，而是环境链路中某个环节断裂：kratos命令未安装、go.mod版本冲突、模板拉取超时、HTTP路由未注册、端口被占等都可能直接导致服务起不来。
kratos命令找不到或new后项目跑不起来
第一步：检查kratos是否已全局安装并加入PATH。运行which kratos或kratos version，若提示command not found，说明kratos二进制未正确安装或PATH未生效。
第二步：确认Go版本≥1.21，且已启用Go Modules（go env GO111MODULE输出应为on）。旧版Go或模块关闭会导致kratos new生成的go.mod缺失或依赖解析失败。
第三步：手动执行go install github.com/go-kratos/kratos/cmd/kratos/v2@latest重装kratos CLI，安装完成后务必重启终端或运行source ~/.zshrc（或对应shell配置文件）使PATH更新生效——【PATH未刷新是新手最常忽略的致命点】。
第四步：kratos new后进入项目目录，先运行go mod tidy，再检查是否存在cmd/<project>/main.go</project>和internal/server/http/http.go。若main.go缺失或路径异常，大概率是模板拉取中断所致，可删掉项目重试，或改用国内镜像源拉取：KRATOS_TPL_URL=https://gitee.com/go-kratos/kratos-layout.git kratos new demo。
proto编译失败：missing file、plugin not found、syntax error
方法一：检查protoc是否已安装且版本≥3.19。运行protoc --version，若未安装，Linux/macOS请用brew install protobuf或从GitHub releases下载预编译包；Windows用户建议使用scoop：scoop install protobuf。
方法二：确认protoc-gen-go与protoc-gen-go-http插件已安装。执行go install google.golang.org/protobuf/cmd/protoc-gen-go@latest和go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest。注意：插件名末尾的/v2不可省略，否则生成器无法识别。
方法三：proto文件中import路径必须以api/开头，例如import "api/helloworld/v1/helloworld.proto";。若写成相对路径或绝对路径（如./helloworld.proto），protoc将无法解析——【路径错误是syntax error类报错的头号元凶】。
服务启动后访问404或端口无响应
先确认HTTP Server是否真正注册了路由。打开internal/server/http/http.go，检查srv := http.NewServer(...)之后是否有类似srv.HandlePrefix("/", helloworld.NewHelloWorldHandler(...))的挂载逻辑。没有这行，服务就只是个空壳，监听了端口但不处理任何请求。
再检查configs/config.yaml中的http.addr是否被其他进程占用。运行lsof -i :8000（macOS/Linux）或netstat -ano | findstr :8000（Windows）查端口占用情况。若被占用，要么改配置，要么杀掉冲突进程。
最后验证proto生成代码是否已重新生成。修改过api/下proto后，必须重新运行make proto或kratos proto client api/helloworld/v1/helloworld.proto，否则handler结构体与路由绑定会失效，导致404。
