# 注册层失败：处理 tar 文件时出错（退出状态 1）：写入 /app/node_modules/.cache/...：设备上没有剩余空间

- **ID:** `docker/tar-file-too-large-for-layer`
- **领域:** docker
- **类别:** resource_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

Docker 构建上下文或中间层包含一个大文件（例如 node_modules 缓存），超出了 Docker 存储驱动（overlay2）中的可用磁盘空间。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Docker Desktop 4.23.0 | active | — | — |
| Docker Engine 24.0.7 | active | — | — |
| overlay2 storage driver | active | — | — |
| Node.js 18.18.0 | active | — | — |
| npm 10.2.0 | active | — | — |

## 解决方案

1. ```
   添加 .dockerignore 文件以排除大型目录，如 node_modules：'**/node_modules/**' 和 '**/.cache/**'，以减少构建上下文大小。
   ```
2. ```
   在 Docker Desktop 中增加磁盘映像大小：设置 > 资源 > 高级 > 磁盘映像大小（例如从 64GB 增加到 128GB）。然后应用并重启 Docker。
   ```
3. ```
   使用多阶段构建，仅复制必要的工件：'COPY --from=builder /app/dist /app'，避免将整个 node_modules 复制到最终阶段。
   ```

## 无效尝试

- **Adding more RAM to the Docker VM (Docker Desktop settings)** — RAM allocation does not affect disk space in the storage driver; the error is about disk space, not memory. Increasing RAM may help other issues but not this one. (90% 失败率)
- **Running 'docker system prune -a' to clean all unused data** — While pruning frees space, it does not prevent the build from generating large layers again; the error will recur if the same large file is in the context. (50% 失败率)
- **Setting 'DOCKER_BUILDKIT=0' to disable BuildKit** — Disabling BuildKit uses the legacy builder which has the same disk space limitation; it may even be more space-intensive due to less efficient caching. (75% 失败率)