如何在Docker构建中传入GitLab Job Token且不触发缓存失效？

下面是几个实用的解决思路，针对你遇到的CI_JOB_TOKEN每次变化破坏Docker缓存的问题：

方案1：用Docker BuildKit临时挂载令牌（推荐） #

借助Docker BuildKit的临时挂载功能，让令牌只在构建时临时可用，不会写入镜像层，也不会影响缓存哈希计算。

步骤1：修改Dockerfile #

开头声明使用BuildKit语法，然后用--mount挂载令牌：

# syntax=docker/dockerfile:1.4
FROM python:3.9

WORKDIR /project

# 先复制依赖文件，这一步缓存仅在poetry.lock或pyproject.toml变更时失效
COPY poetry.lock pyproject.toml ./
RUN pip install poetry

# 临时挂载令牌，配置认证后执行安装，命令内容固定不影响缓存
RUN --mount=type=secret,id=CI_JOB_TOKEN \
    poetry config http-basic.gitlab-pypi-repo gitlab-ci-token "$(cat /run/secrets/CI_JOB_TOKEN)" && \
    poetry install --no-interaction

步骤2：GitLab CI中启用BuildKit并传递令牌 #

在CI构建命令里开启BuildKit，同时把CI_JOB_TOKEN作为secret传入：

DOCKER_BUILDKIT=1 docker build --secret id=CI_JOB_TOKEN="$CI_JOB_TOKEN" -t your-image-name .

核心优势：挂载操作是临时的，RUN命令内容完全固定，Docker会正常缓存该步骤，只要前面的依赖文件没变化，就不会重新执行耗时的安装流程。

方案2：合并认证与安装命令，减少缓存失效点 #

把poetry config和poetry install合并成一个步骤，虽然令牌变化仍会让这一步重新执行，但前面的依赖文件复制、Poetry安装步骤能保留缓存，且Poetry会根据poetry.lock跳过已安装的依赖：

修改后的Dockerfile：

FROM python:3.9

WORKDIR /project

COPY poetry.lock pyproject.toml ./
RUN pip install poetry

ARG CI_JOB_TOKEN
# 合并配置与安装命令，减少缓存层级的影响
RUN poetry config http-basic.gitlab-pypi-repo gitlab-ci-token ${CI_JOB_TOKEN} && \
    poetry install --no-interaction

这个方案的好处是Dockerfile改动小，缺点是每次构建仍会执行poetry install，但因为lock文件锁定了依赖版本，Poetry只会校验已安装的包，不会重新下载，速度比从头构建快很多。

方案3：用GitLab CI缓存加速依赖下载 #

在GitLab CI中配置缓存，把Poetry的依赖缓存目录存下来，即使Docker缓存失效，也能快速复用已下载的包：

步骤1：配置.gitlab-ci.yml的缓存 #

cache:
  paths:
    - ~/.cache/pypoetry/  # Poetry的全局缓存目录
    - .venv/              # 项目虚拟环境（如果使用的话）

步骤2：调整Dockerfile #

FROM python:3.9

WORKDIR /project

COPY poetry.lock pyproject.toml ./
RUN pip install poetry

ARG CI_JOB_TOKEN
RUN poetry config http-basic.gitlab-pypi-repo gitlab-ci-token ${CI_JOB_TOKEN}
# 先安装依赖（不安装项目本身），利用CI缓存加速
RUN poetry install --no-interaction --no-root

这样即使Docker的安装步骤重新执行，Poetry会优先从CI缓存中读取已下载的包，不需要重复从GitLab PyPI仓库拉取，大幅节省时间。

方案4：使用长期个人访问令牌（谨慎使用） #

如果内部安全管控允许，可以用GitLab个人访问令牌（PAT）代替临时的CI_JOB_TOKEN，把PAT存在GitLab CI的私密变量中。因为令牌固定，Docker缓存不会因为令牌变化失效：

步骤1：修改Dockerfile #

FROM python:3.9

WORKDIR /project

COPY poetry.lock pyproject.toml ./
RUN pip install poetry

ARG GITLAB_PYPI_TOKEN
RUN poetry config http-basic.gitlab-pypi-repo gitlab-ci-token ${GITLAB_PYPI_TOKEN}
RUN poetry install --no-interaction

步骤2：在GitLab CI中配置变量 #

在项目的「Settings > CI/CD > Variables」里添加GITLAB_PYPI_TOKEN，值为你的个人访问令牌（需配置读取PyPI仓库的权限）。然后在构建命令中传递：

docker build --build-arg GITLAB_PYPI_TOKEN="$GITLAB_PYPI_TOKEN" -t your-image-name .

注意：这个方案存在令牌泄露风险，需要定期轮换令牌，并严格控制令牌的权限范围。

内容的提问来源于stack exchange，提问作者daphtdazz