注册层失败：处理 tar 文件时出错（退出状态 1）：写入 /app/node_modules/.cache/...：设备上没有剩余空间
failed to register layer: Error processing tar file(exit status 1): write /app/node_modules/.cache/...: no space left on device
ID: docker/tar-file-too-large-for-layer
版本兼容性
| 版本 | 状态 | 引入 | 弃用 | 备注 |
|---|---|---|---|---|
| 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 | — | — | — |
根因分析
Docker 构建上下文或中间层包含一个大文件（例如 node_modules 缓存），超出了 Docker 存储驱动（overlay2）中的可用磁盘空间。
English
The Docker build context or intermediate layer contains a large file (e.g., node_modules cache) that exceeds the available disk space in the Docker storage driver (overlay2).
官方文档
https://docs.docker.com/engine/reference/commandline/builder_prune/解决方案
-
添加 .dockerignore 文件以排除大型目录，如 node_modules：'**/node_modules/**' 和 '**/.cache/**'，以减少构建上下文大小。
-
在 Docker Desktop 中增加磁盘映像大小：设置 > 资源 > 高级 > 磁盘映像大小（例如从 64GB 增加到 128GB）。然后应用并重启 Docker。
-
使用多阶段构建，仅复制必要的工件：'COPY --from=builder /app/dist /app'，避免将整个 node_modules 复制到最终阶段。
无效尝试
常见但无效的做法:
-
Adding more RAM to the Docker VM (Docker Desktop settings)
90% 失败
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.
-
Running 'docker system prune -a' to clean all unused data
50% 失败
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.
-
Setting 'DOCKER_BUILDKIT=0' to disable BuildKit
75% 失败
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.