# 警告：环境变量 'GIT_COMMIT' 的更改使构建缓存失效。

- **ID:** `docker/build-cache-invalidation-due-to-env`
- **领域:** docker
- **类别:** build_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

Docker 构建使用带有动态变量（例如 git 提交哈希）的 --build-arg，该变量每次构建都会更改，导致所有后续层被重建。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Docker 24.0.6 | active | — | — |
| Docker 25.0.2 | active | — | — |

## 解决方案

1. ```
   将 ARG 声明放在所有稳定层之后（例如 apt-get install 之后），以便仅重建最终层，例如在 Dockerfile 末尾放置 'ARG GIT_COMMIT'。
   ```
2. ```
   在缓存依赖项之后使用单独的标签指令，如 'LABEL git.commit=$GIT_COMMIT'，仅将 build-arg 用于元数据。
   ```

## 无效尝试

- **** — Removing the --build-arg entirely loses the dynamic value needed for labeling or debugging. (60% 失败率)
- **** — Adding the ARG after RUN commands in Dockerfile still invalidates cache for those layers. (90% 失败率)