Kratos微服务Docker构建易出错，主因是未适配其cmd/{service}/main.go结构及Go模块依赖；须用多阶段构建，显式指定包路径、静态编译、仅COPY二进制，并验证配置文件路径、目录权限与端口监听。
直接用 docker build 打包 Kratos 微服务，大概率会出错——不是镜像体积爆炸，就是运行时报 main: not found 或 no such file or directory。根本原因在于：Kratos 项目默认生成的是 Go 模块结构，而多数人抄的 Dockerfile 没适配它的构建入口、依赖管理和二进制打包路径。
确认 Kratos 项目的 main 包位置和构建命令
Kratos 的 CLI 生成的项目，main.go 不在根目录，而是在 cmd/{service-name}/main.go（比如 cmd/user/main.go）。这意味着：
-
go build必须显式指定包路径：go build -o ./bin/user ./cmd/user，不能只写go build -o ./bin/user . - 如果项目启用了
go.work或多模块（如含api/、internal/、third_party/），go build还可能因未识别依赖路径失败 - 很多教程里写的
COPY . .+go build在容器内执行，会把整个vendor或go.sum冲突项带进去，导致构建失败或镜像臃肿
用多阶段构建（multi-stage）生成最小化镜像
别再用 FROM golang:1.23 直接跑生产环境。Kratos 服务是纯 Go 二进制，静态链接后只需 FROM scratch 或 FROM gcr.io/distroless/static。关键点：
- 第一阶段用
golang:1.23-alpine（更小、更安全）编译，记得加-ldflags="-s -w"去掉调试信息 - 第二阶段 COPY 编译产物时，只 COPY 二进制文件，**不要 COPY
go.mod、go.sum、cmd/目录或源码** - 必须显式设置
WORKDIR /app并COPY --from=0 /workspace/bin/user /app/user（假设你go build -o /workspace/bin/user ./cmd/user） - 启动命令写成
ENTRYPOINT ["/app/user"]，别用CMD，避免被 docker run 参数覆盖
示例关键片段：
FROM golang:1.23-alpine AS builder WORKDIR /workspace COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 go build -a -ldflags="-s -w" -o ./bin/user ./cmd/user FROM gcr.io/distroless/static WORKDIR /app COPY --from=builder /workspace/bin/user /app/user ENTRYPOINT ["/app/user"]
避免 docker build 时因本地 GOPROXY 或网络导致失败
本地 go env GOPROXY 是 https://proxy.golang.org，但构建机可能无法访问。Docker 构建过程中不会继承宿主机的 GOPROXY 设置，所以：
- 在
Dockerfile的 builder 阶段开头加一行：ENV GOPROXY=https://goproxy.cn,direct（国内推荐） - 如果项目用了私有模块（如公司内部 GitLab 的
git.example.com/go/mylib），必须在go.mod中配置replace或在构建时挂载~/.netrc，否则go mod download会卡住或 401 - 别信“本地
go build成功，Docker 就一定成功”——容器里没$HOME、没 ssh-agent、没 git config，go get私有库必挂
发布前必须验证的三个检查点
镜像 build 完不等于能跑。Kratos 服务启动失败，80% 出在运行时环境缺失：
- 检查
config.yaml是否随镜像 COPY 进去？路径是否对？Kratos 默认读./configs/config.yaml，不是/etc/app/config.yaml - 检查
log和data目录是否有写权限？distroless镜像默认以 UID=65532 运行，若你的日志路径是/app/logs且没RUN mkdir -p /app/logs && chown -R 65532:65532 /app/logs，服务启动即 panic - 检查
grpc或http端口是否被硬编码为0.0.0.0:9000？Kubernetes Service 默认只暴露一个端口，若你在configs/config.yaml里写了http.addr: "0.0.0.0:9000"，但 K8s YAML 中只 expose 了 9001，就会监听失败却无明显报错
最稳妥的做法：先 docker run -it --rm -p 9000:9000 your-kratos-image 手动跑一次，看日志是否输出 server started 和实际监听地址；再 curl http://localhost:9000/health 确认 HTTP server 可达。
