ko build 找不到 main 包是因为它严格复用 go list 的包发现逻辑，仅识别当前目录下能被 go list -f '{{.Name}}' . 输出 main 且含 go.mod 的目录，不支持混入 internal/、pkg/ 或非规范测试文件。
ko 能完全绕过 Docker daemon 和 Dockerfile，但必须满足 Go 模块结构、镜像仓库可写、基础镜像可拉取三个硬条件，缺一不可。
ko build 找不到 main 包的常见原因
这不是 ko 的 bug，而是它严格复用 go list 的包发现逻辑。它只认当前目录下能被 go list -f '{{.Name}}' . 输出 main 的目录，且该目录必须有 go.mod。
- 在项目根目录执行
ko build ./cmd/myapp—— 正确，前提是./cmd/myapp里有main.go和go.mod（或上层有） - 在
./cmd/myapp目录内执行ko build .—— 也正确，但要求该目录下不能混入internal/、pkg/或命名不规范的_test.go文件 - 执行
ko build github.com/your/repo/cmd/myapp—— 仅当本地 GOPATH 或模块路径能解析该 import path，否则报no matching packages - 如果
go build ./cmd/myapp本地都失败，ko 必定失败 —— 先跑通这个再试 ko
KO_DOCKER_REPO 配置错误导致 push 失败
ko 不支持 localhost:5000 这类 insecure registry，默认拒绝未 TLS 的地址。它也不读 /etc/docker/daemon.json，只认 Docker CLI 的 credential store 或显式配置。
- 最稳妥方式：
KO_DOCKER_REPO=ghcr.io/yourname ko build ./cmd/app—— 环境变量优先级最高 - 若用 Google Artifact Registry：
export KO_DOCKER_REPO=us-east1-docker.pkg.dev/your-project-id/my-repo，并确保已运行gcloud auth configure-docker或设置了GOOGLE_APPLICATION_CREDENTIALS - 避免在
.ko.yaml中硬编码 registry —— 容易和 CI 环境冲突；环境变量更适合多环境切换 - 镜像名最终由
KO_DOCKER_REPO+ 包路径推导，例如KO_DOCKER_REPO=docker.io/me+./cmd/api→docker.io/me/api
ko 构建结果体积异常大的排查点
ko 默认用 gcr.io/distroless/static:nonroot，但如果你看到镜像 >50MB，大概率是 CGO 或 base image 被意外替换。
立即学习“go语言免费学习笔记（深入）”；
- 检查是否无意启用了
CGO_ENABLED=1—— ko 内部强制设为0，但若你在.ko.yaml里覆盖了defaultBaseImage到 alpine/ubuntu，就会引入大量系统库 - 确认没在
main.go里 import"C"或调用cgo相关函数 —— 否则编译会静默回退到动态链接，ko 无法打包依赖库 - 运行
ko build --sbom=none -v ./cmd/app查看 verbose 日志，重点观察 “Using base …” 行是否为你预期的基础镜像 - 用
ko run ./cmd/app本地测试启动 —— 如果 panic “no such file or directory”，基本就是动态链接问题
CI 环境中 ko 构建失败的隐性依赖
ko 本身不依赖 Docker daemon，但它依赖三样东西：Go 编译器、镜像仓库凭证、基础镜像网络可达性。CI 中最容易漏掉的是后两者。
- 基础镜像（如
gcr.io/distroless/static）需从公网拉取 —— 若 CI 环境走代理或私有 registry mirror，需提前配置~/.docker/config.json或设置HTTP_PROXY - 凭证必须由
docker login写入~/.docker/config.json—— ko 不读~/.config/ko/config.yaml，只认 Docker CLI 标准路径 - Git 信息缺失不影响构建，但会影响 tag 渲染（如
{{ .Commit }}）—— 若你依赖 commit hash 做 tag，CI 中需保证工作区是完整 git clone（非 shallow） - 别在 CI 中用
--insecure-registry参数 —— 它绕过 TLS 校验，但多数企业 registry 不允许，且 ko v0.12+ 已标记为 deprecated
真正麻烦的不是 ko 本身，而是它把原本藏在 Dockerfile 里的隐性假设全暴露出来了：模块路径是否干净、registry 是否可信、基础镜像是否可访问。一旦出错，往往不是 ko 的问题，而是这些底层契约没对齐。
