kratos new 必须指定项目名，如 kratos new user，不支持空参数或--name；生成完整微服务骨架，含标准分层结构和依赖注入，需配合kratos proto server生成代码并确保protoc插件安装。
kratos new 命令必须指定项目名，不能省略
直接运行 kratos new 会报错：「flag needs an argument: -h」或提示 usage。Kratos 要求你明确提供服务名，比如 kratos new user，它不是交互式向导，不支持空参数回车继续。
常见错误现象：
– 执行 kratos new 后卡住或报错退出
– 误以为能用 kratos new --name=user（实际不支持长 flag）
– 在已有 Go module 目录下重复执行，导致 go.mod 冲突
- 服务名必须是合法的 Go 包名（小写字母、数字、下划线，不能以数字开头）
- 若在国内拉取模板慢或失败，加
-r指向镜像源：kratos new user -r https://gitee.com/go-kratos/kratos-layout.git - 不建议在
$GOPATH/src下创建，推荐放在任意路径 +go mod init管理，避免 GOPATH 语义干扰
kratos new 生成的是完整骨架，不是空目录
执行 kratos new user 后，你会立刻得到一个含标准分层结构的 Go 项目：包括 api/（proto）、internal/biz/（业务逻辑）、internal/data/（数据访问）、internal/service/（RPC 实现）、configs/、cmd/ 和 Makefile。它不是“新建一个 service 文件”，而是新建一个可独立部署的微服务进程。
这意味着：
– 你不需要手动建 internal/service/user.go，它已存在（默认带 Greeter 示例）
– api/helloworld/v1/greeter.proto 是占位文件，删它前先确认是否要保留 HTTP/gRPC 双协议能力
– cmd/server/main.go 已绑定 Wire 依赖注入，不要删 wire.go 或改错 wire_gen.go 的生成逻辑
- 如只需纯 RPC 服务（无 HTTP），可删掉
api/helloworld/v1/greeter_http.pb.go和internal/server/http.go - 若想复用已有
go.mod（例如多服务共用一个 module），加--nomod参数：kratos new user --nomod - 生成后立即运行
go mod tidy，确保所有依赖（尤其是google.golang.org/protobuf）版本对齐，否则后续make api会失败
kratos proto add 和 kratos proto server 必须配合使用
新增一个用户服务接口，不能只写 user.proto 就完事。kratos proto add 只是把文件放进 api/ 目录并初始化结构；真正生成 Go 代码靠 kratos proto server —— 它调用 protoc + Kratos 插件，产出 *.pb.go、*_grpc.pb.go 和 *_http.pb.go。
典型错误：
– 修改了 user.proto 但忘记跑 kratos proto server api/user/v1/user.proto -t internal/service，导致 internal/service/user.go 中引用的类型（如 v1.CreateUserInfo）报红
– 用 protoc 手动编译，但没加 Kratos 的 HTTP 插件，结果缺失 REST 路由绑定逻辑
– -t 参数路径写错，比如写成 internal/service/user（多了 /user），导致生成文件进错目录
-
kratos proto server的-t参数指定的是 Go struct 的目标包路径，不是文件系统路径，应为internal/service（对应package service） - 生成后检查
api/user/v1/user_grpc.pb.go是否含RegisterUserServer，以及user_http.pb.go是否含RegisterUserHandlerFromEndpoint，缺一不可 - 若报错
protoc-gen-go-http: program not found，说明没装插件：go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest
make api 失败时优先检查 protoc 插件和路径变量
make api 本质是调用 protoc 扫描 api/ 下所有 .proto 并批量生成。它比手敲 kratos proto server 更适合多 proto 场景，但失败原因更隐蔽。
常见失败点：
– protoc 命令未加入 $PATH，make 找不到它（Linux/macOS 运行 which protoc 验证）
– Windows 下 Makefile 用 find 命令，但系统自带 find.exe 不兼容 POSIX 语法，Kratos 的 Makefile 已尝试用 Git Bash 替代，但若没装 Git 或路径含空格，仍会崩
– GOHOSTOS 变量识别错误，导致 INTERNAL_PROTO_FILES 为空，make api 实际什么都没做
- 临时绕过 Makefile：直接用
protoc --proto_path=api --go_out=paths=source_relative:./api --go-grpc_out=paths=source_relative:./api --go-http_out=paths=source_relative:./api api/user/v1/user.proto - 确保
api/下的.proto文件里option go_package值与实际 Go 包路径一致（如user/api/user/v1;v1对应api/user/v1/目录） - 如果 proto 引用了
google/api/annotations.proto，确认third_party/google/api/存在且内容完整，否则protoc报File not found
最易被忽略的一点：Kratos 的 kratos new 生成的服务默认监听 :9000（gRPC）和 :8000（HTTP），但端口冲突不会报错，只会静默失败——检查日志里有没有 [gRPC] server listening on 这行，没有就说明启动卡在了服务注册或 DB 初始化阶段，别急着查 proto 生成问题。
