GitLab CI 中通过 .gitlab-ci.yml 的 image 关键字指定作业容器镜像，支持官方或私有镜像；可自定义构建并推送镜像，按需在 job 或 default 级别配置，配合 services 使用，并需确保 runner 具备拉取权限与验证能力。
GitLab CI 中配置自定义构建镜像，核心是通过 .gitlab-ci.yml 文件的 image 关键字指定作业运行所用的容器镜像。这个镜像就是作业执行时的“操作系统环境”，直接影响命令能否运行、依赖是否就绪、构建是否稳定。
明确指定基础镜像
在 job 级别或全局 default 区块中设置 image，值为 Docker 镜像的完整地址（含 registry、仓库名和标签）：
- 使用官方镜像：如
image: python:3.11-slim或image: node:20-alpine - 使用私有镜像：如
image: registry.example.com/my-team/base-images/python-dev:1.2 - 省略标签时默认为
:latest，但强烈建议显式指定版本号，避免因镜像更新导致构建不一致
构建并托管你自己的构建镜像
若标准镜像不满足需求（比如缺编译工具、预装特定 CLI、集成内部证书或代理配置），可自行构建定制镜像：
GitCode API Usage
下载
简单易用的 GitCode API SKILL，提供 CLI 和轻量级 Python SDK 两种调用方式，用于与 GitCode 的 REST API 进行交互。支持加密访问令牌、异步调用以及完善的类型提示。 - 文档：https://gitcode-api.readthedocs.io/ - PyPI 页面：https://pypi.org/project/gitcode-api - GitHub 仓库：https://github.com/Trenza1ore/GitCode-API
- 编写
Dockerfile，例如安装 Java、Maven、kubectl、helm 及公司内部 CA 证书 - 在 CI 流水线中用
docker build构建该镜像（需 runner 支持 Docker-in-Docker 或使用 Kaniko） - 推送到 GitLab Container Registry 或其他私有仓库（如 Harbor）
- 在后续流水线中通过
image:引用该镜像，例如image: $CI_REGISTRY_IMAGE/build-env:java17-mvn39
按需覆盖或继承镜像配置
不同 job 可以使用不同镜像，也可复用 base 镜像并叠加变更：
- 全局设默认镜像：
default: { image: registry.example.com/base:ubuntu22.04 } - 个别 job 覆盖：
build-java: { image: registry.example.com/base:java17, script: [ ... ] } - 配合
services使用：例如主镜像跑构建脚本，同时启用services: [ postgres:15 ]提供测试数据库
验证镜像可用性与权限
确保 runner 能拉取该镜像：
- 私有 registry 需提前配置认证：在项目 Settings > CI/CD > Variables 中添加
CI_REGISTRY_USER和CI_REGISTRY_PASSWORD - 或在
before_script中执行docker login（适用于复杂鉴权场景） - 首次使用新镜像时，可在简单 job 中仅运行
echo "OK"并查看日志是否成功启动容器，快速验证镜像拉取与基础运行能力
