Kratos生产镜像需分阶段构建：builder阶段安装protoc、生成proto文件并静态编译，runtime阶段用alpine基础镜像，显式COPY二进制、configs/、templates/，设置-ca-certificates和-conf路径，避免exec format error与file not found。
直接用 docker build 打包 Kratos 微服务镜像，核心是避免把开发环境、proto 生成物、调试工具一并塞进生产镜像——否则镜像臃肿、启动慢、有安全风险。
为什么不能直接 go build 后 cp 二进制进基础镜像
Kratos 项目通常依赖 proto 生成的 *.pb.go 和 *.grpc.pb.go，还可能读取 configs/ 下的 YAML、加载 templates/ 或访问本地文件路径。如果只拷二进制，运行时大概率 panic 报 file not found 或 unknown service。
常见错误现象：
-
panic: proto: file not registered—— proto 注册缺失，通常是init()没触发或生成文件没编译进去 -
open configs/app.yaml: no such file or directory—— 配置文件没 COPY 进镜像，或启动时没指定-conf路径 - 服务注册失败但日志无报错 —— 实际是
consul.New()返回nil，而kratos.New()收到 nil 后直接 panic（不提示具体哪个参数）
Dockerfile 必须分阶段构建
Go 编译依赖完整 Go 环境和 proto 工具链，但运行只需静态二进制和必要资源。硬塞一个 golang:1.22 镜像上线，镜像大小轻松破 1GB，且含大量非必要工具（git、curl、protoc），违反最小化原则。
推荐写法（以标准 Kratos 模板结构为例）：
FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . # 确保 proto 已生成（关键！） RUN protoc --go_out=paths=source_relative:. --go-grpc_out=paths=source_relative:. api/*.proto RUN CGO_ENABLED=0 go build -a -ldflags '-extldflags "-static"' -o /usr/local/bin/app . <p>FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /usr/local/bin/app . COPY configs/ ./configs/ COPY templates/ ./templates/ EXPOSE 9000 8000 CMD ["./app", "-conf", "./configs"]
注意点：
- 必须在
builder阶段显式执行protoc，不能依赖本地已生成的文件（CI 环境无缓存） -
CGO_ENABLED=0保证静态链接，避免 Alpine 上缺 libc 报错 -
configs/和templates/必须显式COPY，不能靠二进制内嵌（Kratos 默认不 embed） - 启动命令里
-conf路径要和COPY目标一致，否则找不到配置
构建命令与环境变量控制
本地测试时，常需切换 registry 地址或关闭健康检查。这些不该硬编码进 Dockerfile，而应通过构建参数或运行时环境注入。
构建时传参示例：
docker build \ --build-arg CONSUL_ADDR="consul:8500" \ --build-arg ENV="prod" \ -t myapp:v1.2.0 .
对应 Dockerfile 中可加：
ARG CONSUL_ADDR ARG ENV ENV CONSUL_ADDR=$CONSUL_ADDR ENV ENV=$ENV
这样 Kratos 启动时就能读到 os.Getenv("CONSUL_ADDR")，不用改代码。但注意：kratos.New() 初始化前必须确保环境变量已就位，否则 consul.New() 可能因地址为空返回 nil，引发 panic。
容易踩的坑：
- 忘记在
builder阶段安装protoc：Alpine 需apk add protobuf-dev；Debian/Ubuntu 用apt install protobuf-compiler - proto 文件路径写错，比如
api/hello/v1/hello.proto却只COPY api/，漏了v1/子目录 - 用
go run main.go测试没问题，但镜像里没main.go—— Kratos 模板默认入口是cmd/app/main.go，COPY时别漏掉
最易被忽略的是：proto 生成逻辑必须和 Go 模块路径严格对齐。哪怕 go_package 少了个 v1，生成的 package 名就不匹配，编译不报错，运行时却找不到 service 注册项——这种问题不会出现在日志开头，得查到第三层调用栈才看到 unregistered service。
