gitlab ci中多平台docker镜像构建失败主因是buildx builder未初始化、registry镜像命名不规范及基础镜像abi不匹配；需显式创建builder、统一debian系基础镜像、启用缓存并严格小写无符号tag。
GitLab CI里用docker buildx构建多平台镜像失败，缺builder实例
默认的GitLab Runner没启用buildx builder，docker buildx build --platform会直接报错error: no builder found。必须显式创建并切换到支持多架构的builder。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
.gitlab-ci.yml的before_script或首个job里运行docker buildx create --name multiarch --use --bootstrap - 确保Runner使用
docker:dind服务，并开启privileged: true——否则buildx无法挂载QEMU binfmt - 如果用自建Runner，宿主机需提前执行
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes，否则ARM构建时卡在exec format error
Go交叉编译二进制后Docker镜像仍报exec format error
Go本身能跨平台编译（比如GOOS=linux GOARCH=arm64 go build），但Docker镜像基础层不匹配就会出错。常见于用了golang:alpine做构建阶段，却用scratch或debian:slim做运行阶段，而后者缺少ARM64动态链接库或ABI兼容性。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 构建阶段用
golang:1.22-bookworm（Debian系）比alpine更稳妥，尤其要跑ARM时 - 运行阶段优先选
scratch（静态编译Go二进制）或debian:bookworm-slim，避免混用Alpine和Debian基础镜像 - 确认Go编译时加了
-ldflags="-s -w"和CGO_ENABLED=0，否则二进制可能依赖宿主机glibc
docker buildx build在CI中缓存失效、每次全量重建
GitLab CI默认每个job是干净环境，buildx的构建缓存不自动跨job保留，导致重复拉取依赖、编译慢、镜像层冗余。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
--cache-from type=registry,ref=$CI_REGISTRY_IMAGE/cache:build和--cache-to type=registry,ref=$CI_REGISTRY_IMAGE/cache:build,mode=max - 确保
$CI_REGISTRY_IMAGE可写，且Runner有docker login凭证（通过CI_REGISTRY_USER/CI_REGISTRY_PASSWORD注入） - 缓存镜像标签别用
latest，改用build-$CI_COMMIT_REF_SLUG之类带分支名的，避免不同分支互相污染
推送镜像时提示denied: requested access to the resource is denied
这不是权限不足，而是GitLab Registry对镜像命名规则敏感：tag必须全小写、只含字母数字和短横线，且仓库路径不能含大写或下划线。Go项目名带MyApp或my_app，直接用于DOCKER_IMAGE就触发拒绝。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在CI变量里定义
IMAGE_NAME为myapp（小写无符号），再拼成$CI_REGISTRY/$CI_PROJECT_PATH:$IMAGE_NAME-$CI_COMMIT_TAG - 用
sed 's/[^a-z0-9\-]//g' 清洗项目名，避免意外字符 - 推送前加一步
docker images $DOCKER_IMAGE确认镜像存在且tag正确——经常是docker tag漏写了
多平台构建真正卡点不在Go编译，而在buildx环境初始化和Registry的命名洁癖。一旦builder没起来、缓存没推上、tag里混进下划线，整个流水线就静默失败，日志里只显示“exited with code 1”。
