通过GitHub Actions构建Docker镜像时如何传入API密钥等敏感信息？

以下是经过生产环境验证的可行方案，按安全性从高到低排序：

方案1：使用 BuildKit 挂载临时密钥（最推荐，无密钥残留风险） #

适合多密钥、配置文件类敏感信息的场景，密钥不会残留在镜像层或构建历史中：

• 先将敏感配置文件的完整内容存入仓库的 GitHub Secrets，路径为「仓库 Settings → Secrets and variables → Actions → New repository secret」，命名为APP_CONFIG
• 在 GitHub Actions 工作流文件中，先将密钥内容写入临时文件，再启用 BuildKit 构建镜像并挂载密钥：

- name: 生成临时配置文件
  run: echo "${{ secrets.APP_CONFIG }}" > .env

- name: 构建 Docker 镜像
  run: |
    DOCKER_BUILDKIT=1 docker build \
      --secret id=env,src=.env \
      -t 你的镜像名:版本号 .

• 在 Dockerfile 中通过临时挂载路径读取密钥，仅当前构建步骤可访问：

# 只在需要用到密钥的构建步骤挂载，构建完成后临时文件会自动销毁
RUN --mount=type=secret,id=env \
    # 加载配置文件中的所有环境变量
    export $(cat /run/secrets/env | xargs) && \
    # 执行需要用到密钥的构建操作，比如前端打包、后端编译等
    npm run build

方案2：通过构建参数传递（适合少量单一密钥场景） #

操作更简单，适合仅需要传递1-2个密钥的场景，需要额外注意清除镜像层残留：

• 先将单个 API Key 存入 GitHub Secrets，命名为API_KEY
• 在工作流的构建步骤中传递构建参数：

- name: 构建 Docker 镜像
  run: |
    docker build \
      --build-arg API_KEY=${{ secrets.API_KEY }} \
      -t 你的镜像名:版本号 .

• 在 Dockerfile 中声明参数并使用：

# 声明构建参数，作用域为声明位置到构建结束
ARG API_KEY

# 执行构建操作
RUN npm run build

# *如果后续不需要用到该参数，建议主动清空避免残留*
RUN unset API_KEY

注意：不要将构建参数赋值给 ENV 变量，ENV 变量会永久保存在镜像层中，可被任意获取镜像的人通过docker inspect查看到

禁止操作 #

• 不要在 Dockerfile 中硬编码任何密钥，也不要通过 COPY 指令将本地配置文件打包到镜像中
• 不要在工作流日志中打印任何密钥内容，GitHub 会自动屏蔽 Secrets 内容，但手动echo仍可能存在泄露风险

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