# 错误：无法解析：计算缓存键失败：无法计算引用的校验和...：未找到

- **ID:** `cicd/docker-buildkit-export-failed`
- **领域:** cicd
- **类别:** build_error
- **错误码:** `BUILDKIT_CACHE_KEY_ERROR`
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

Docker BuildKit 缓存导出失败，因为引用的缓存层丢失或损坏，通常是由于并发构建覆盖了相同的缓存或缓存上传不完整。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Docker 24.0.5 | active | — | — |
| BuildKit 0.12.2 | active | — | — |
| Ubuntu 22.04 | active | — | — |

## 解决方案

1. ```
   Invalidate the specific cache key by adding a unique build argument: docker build --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from type=registry,ref=mycache --cache-to type=registry,ref=mycache,mode=max .
   ```
2. ```
   Use a unique cache tag per build (e.g., cache-<commit-sha>) to avoid collision: docker build --cache-from type=registry,ref=myrepo/cache:${GITHUB_SHA} --cache-to type=registry,ref=myrepo/cache:${GITHUB_SHA} .
   ```
3. ```
   Clear the remote cache entirely: docker buildx rm mybuilder; docker buildx create --use --driver-opt network=host; then rebuild with fresh cache export.
   ```

## 无效尝试

- **Rebuilding the entire Docker image without cache (--no-cache)** — While this bypasses the cache key error, it defeats the purpose of caching and significantly increases build time; the underlying cache corruption is not fixed. (50% 失败率)
- **Manually deleting all Docker cache directories on the runner** — Cache may be stored externally (e.g., on a registry or S3); local deletion doesn't fix remote cache corruption. (80% 失败率)
- **Increasing the build timeout** — The error is not timeout-related; it's a cache integrity issue. (95% 失败率)