# 解决失败：无法计算缓存键：无法计算引用'cache-mount-target'的校验和：未找到

- **ID:** `cicd/docker-buildkit-cache-mount`
- **领域:** cicd
- **类别:** build_error
- **错误码:** `BUILDKIT_CACHE_MOUNT_NOT_FOUND`
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

Docker BuildKit缓存挂载目标目录在构建上下文或基础镜像中不存在，导致在Dockerfile中使用`--mount=type=cache,target=/path`时校验和计算失败。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Docker 25.0 | active | — | — |
| BuildKit 0.12.0 | active | — | — |

## 解决方案

1. ```
   Create the target directory in the Dockerfile before the cache mount is used: add `RUN mkdir -p /var/cache/apt` before the RUN instruction that uses `--mount=type=cache,target=/var/cache/apt`
   ```
2. ```
   Use a different base image that already contains the cache directory, or ensure the directory is included in the build context by creating it locally before build
   ```

## 无效尝试

- **** — Removing the cache mount will break the build if the cache is required for package downloads (e.g., apt, npm); the build may fail due to network timeouts or missing dependencies (70% 失败率)
- **** — Disabling BuildKit removes cache mount support entirely, and the legacy builder may not support the same Dockerfile syntax, causing a different error (50% 失败率)