ko build 找不到 main 包是因为它仅构建当前目录下含 main 函数且能被 go list 识别的包；需确保在含 main.go 和 go.mod 的目录执行，避免混入非 main 包或不规范测试文件。
ko build 命令为什么找不到 main 包
ko 默认只构建当前目录下有 main 函数的 Go 包，且要求该包路径能被 go list 正确识别。如果你在子目录运行 ko build，或 main.go 所在目录里混了其他非 main 包（比如 internal/ 或测试文件），ko 会静默失败或报 no Go files in directory。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确保你在包含
main.go的目录下执行ko build，不是项目根目录也不是cmd/xxx外的任意子目录 - 检查该目录下是否有
go.mod；没有的话ko可能无法推导模块路径，加一个最简的：module example.com/app<br>go 1.21
- 避免在
main目录里放_test.go文件——ko用的是go build -o流程，测试文件会被跳过，但若命名不规范（比如没带_test后缀），可能干扰包解析
如何指定镜像名和 registry 地址
ko 不依赖本地 Docker daemon，但它必须把镜像推到远端 registry（如 ghcr.io、us-east1-docker.pkg.dev），所以镜像名不是随便写的字符串，而是完整 URL 形式。写错会导致 failed to push: failed to authorize request 或 unauthorized: authentication required。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 镜像名必须以 registry 主机名开头，例如：
ghcr.io/yourname/app、us-east1-docker.pkg.dev/your-project-id/my-repo/app - 别用
localhost:5000这类地址——ko默认不支持 insecure registry，除非你显式配置KO_DOCKER_REPO并加--insecure-registry（不推荐） - 用环境变量更稳妥：
KO_DOCKER_REPO=ghcr.io/yourname ko build ./cmd/app，这样不用每次敲全路径 - 如果用 Google Artifact Registry，注意它要求 service account token，得提前运行
gcloud auth configure-docker或设置GOOGLE_APPLICATION_CREDENTIALS
ko build 报错 “no matching packages” 或 “cannot find module”
这是 Go 模块解析失败的典型表现，和 go build 报错逻辑一致，但 ko 不会帮你提示缺失的 go mod init 或 go mod tidy 步骤。尤其当你从旧项目迁移、或 go.mod 里有 replace 指向本地路径时，ko 构建会直接失败——因为它在临时沙箱里运行，看不到你本机的文件系统。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先手动跑一遍
go build -o /tmp/test ./cmd/app，确认本地能编译通过；通不过就别指望ko能行 - 删掉
go.mod里的replace指向本地路径（如replace example.com/lib => ../lib），改用 tagged 版本或发布到私有 proxy - 确保所有依赖都已
go mod download下来，ko不会自动拉取未缓存的 module - 如果用了 Go 1.21+ 的 workspace 模式，
ko目前不支持，得退回到单go.mod结构
ko 构建出的镜像为什么启动就 exit 0
ko 默认用 distroless base 镜像（如 gcr.io/distroless/static:nonroot），它没有 shell、没有 /bin/sh，也不支持 exec 以外的启动方式。如果你的容器启动命令写成 sh -c 'app --flag' 或用了 ENTRYPOINT ["sh", "-c", "..."]，镜像一启动就失败并静默退出。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 永远用 exec 格式启动：直接
ko build --image ghcr.io/x/app ./cmd/app，让ko自动生成正确的ENTRYPOINT - 不要在
Dockerfile里覆盖ENTRYPOINT或CMD——ko不读 Dockerfile，你写了也白写 - 调试时加
--base-image gcr.io/distroless/base:debug，它带busybox和sh，方便进容器查路径、权限、缺失的 so 库 - 如果程序依赖 cgo 或动态链接库（比如 SQLite、OpenSSL），distroless static 镜像不兼容，得换
gcr.io/distroless/cc:nonroot并关掉 CGO_ENABLED=0
真正麻烦的从来不是“能不能构建”，而是 runtime 依赖是否被 distroless base 满足——这点很容易被本地 go run 成功所掩盖。
