Yarn 缓存清理：如何清除 Yarn 缓存（v1, Berry）

快速回答： 热门搜索 yarn clear cache 以及 清除 yarn 缓存，但 Yarn 的 CLI 使用的是 yarn cache clean。检查你正在使用的 Yarn 版本：

yarn --version

运行 yarn config get enableGlobalCache 以查看生效的设置。 Berry 标志： yarn cache clean --all 清除当前活动的缓存范围，并在启用时清除镜像；它并不总是清除机器上所有全局和项目缓存。 yarn cache clean --mirror 仅在存在独立镜像时将其移除，否则可能无操作。 路径检查： Classic yarn cache dir 打印版本化缓存文件夹；完整的 yarn cache clean 会移除其父级缓存根目录。Berry yarn config get cacheFolder.

你在 yarn install，而你刚更新的依赖项仍然解析到旧的 build。或者你的笔记本安装正常，但 CI 在无害的 lockfile 变更后突然失败。缓存行为取决于 Yarn Classic 与 Yarn Berry、缓存范围，以及真正的问题在于 lockfiles 还是 pipeline 缓存设计，而不仅仅是存储的 tarballs。有关更广泛的 CI 依赖项卫生，请参阅 Capacitor OTA 更新 CI/CD 集成.

目录

• 构建失败，Yarn Cache 可能是罪魁祸首
• 何时以及为何清理 Yarn 缓存
  • 缓存出问题的症状
  • 什么时候不该用 Yarn clear cache
• Yarn Classic v1 中的 Yarn cache clean
  • 该命令实际删除了什么
  • 如何确认缓存位置
• Yarn Berry v2+ 的现代缓存管理
  • Berry 改变了缓存模型
  • Berry 中真正重要的命令
• CI/CD 与 Docker 的 Yarn 缓存最佳实践
  • 为什么在 pipeline 中清理缓存往往是错误做法
  • 更好的 CI 和 Docker 方案
• Yarn cache clean 故障排除
  • 当针对性清理后仍残留旧包时
  • 看似缓存问题的权限与环境问题
• 关于清理 Yarn 缓存的常见问题
  • yarn clear cache 的正确命令是什么？
  • 在 Yarn Classic 和 Yarn Berry 中如何运行 yarn cache clean？
  • 清除 Yarn 缓存安全吗？
  • 在 CI 或 Docker 中何时应避免清除 Yarn 缓存？
  • 如何验证 Yarn 缓存的存储位置？
  • 为什么运行 yarn cache clean 后仍会残留旧包？

构建失败，Yarn Cache 可能是罪魁祸首

这种场景你一定不陌生：你升级了一个包，拉取了最新改动，然后再次运行 install。命令执行成功了，但 App 的表现却像旧依赖还在一样。这时有人建议清理缓存，你心里难免会犯嘀咕：这到底是真能解决问题，还是只是某种“玄学”？

它可能是真正的修复，也可能只是干扰。

缓存问题通常以几种可预测的方式出现：本地包无法刷新；CI 拉取了意料之外的内容；或者即便 lockfile 显示一切应该匹配，新分支的表现却与主分支不一致。如果你正在排查更广泛的 pipeline 不稳定性，建议将缓存调试与更系统的构建审查结合起来，例如参考这篇关于 修复 Capacitor CI/CD pipeline 中的构建失败.

实战规则： 要把 Yarn clear cache 当作诊断工具，而不是例行维护仪式。

棘手的地方在于，Yarn 的缓存模型随时间发生了变化。在旧项目中，缓存是全局共享的；而在新项目中，根据命令参数的不同，缓存清理可以是项目本地的、全局的，或者两者兼有。所以当队友说“直接清理 Yarn 缓存吧”时，你首先应该问的是： 是哪种 Yarn？

所以，好的缓存修复要从上下文入手：本地机器还是 CI runner？Yarn v1 还是 Berry？共享缓存还是项目缓存？搞清楚这些，命令才会精准，而不是靠碰运气。

何时以及为何清理 Yarn 缓存

当你心里有具体的故障模式时，清理 Yarn 缓存才有意义。它最实用的场景是：移除过时的包产物、从损坏的下载状态中恢复，或者有意清空已存储的包，让 Yarn 从头重新构建。

缓存出问题的症状

以下情况很适合清理缓存：

• 依赖项拒绝更新： 你改了版本，或重新构建了本地包，但安装时仍然拉取较旧的产物。
• 安装失败像是状态问题： 一台机器正常，另一台不行，重复运行同一条命令总是复现同样的坏结果。
• 你需要释放本地磁盘空间： 这一点在开发者机器上比在短生命周期的 CI 环境中更为重要。

其他情况只是看起来像缓存问题。如果你的 lockfile 意外变更，workspace 配置不一致，或者 Docker build 使错误的层失效，清除缓存无法解决根本原因。从事应用构建的团队在同时处理原生工具、JavaScript 依赖和插件更新时经常遇到这种情况。在此背景下，这份关于 在 Capacitor 项目中管理依赖项的实用概览 值得放在手边。

如果你的目标是更广泛的机器清理，而不是排查包问题，系统级指南也会有所帮助。想要 清理 Mac 用户的应用缓存 的 Mac 开发者通常会发现，包管理器只是存储状况的一部分。

什么时候不该用 Yarn clear cache

不要将 Yarn clear cache 作为应对每个安装问题的首选方案。

当有证据表明包状态陈旧或损坏时使用。如果问题更可能是以下情况，则跳过：

如果安装出错是因为环境配置不当，清除缓存只会让下一次错误的安装变得更慢。

分清这一点能省下不少时间。很多无谓的调试都源于把缓存当成万能的重置按钮。

Yarn Classic v1 中的 Yarn cache clean

Yarn Classic 的行为正是许多开发者默认所有 Yarn 版本都有的行为。它使用一个 全局缓存 位于用户目录中，并且 yarn cache clean 清除该共享缓存。Yarn Classic 的官方文档正是这样描述的，并指出缓存会在下一次 yarn 或 yarn install 在用户目录模型中重新填充，该模型记录于 Yarn Classic 缓存 CLI 文档.

该命令实际删除了什么

对于 Yarn v1，默认的清理命令很简单：

yarn cache clean

该命令会清除共享缓存，而不仅仅是当前项目。如果你在同一台机器上处理多个仓库，这一点很重要。之后在任何仓库中安装依赖时，可能都需要重新获取包。

这种共享缓存设计是 Yarn v1 产生令人困惑的跨项目行为的原因之一。全局缓存中的过期产物可能会存活足够长的时间，从而影响不同的仓库，尤其是在涉及本地包开发时。

Yarn Classic 的实用操作序列通常如下：

1. 首先运行 clean 命令： yarn cache clean
2. 如有需要，删除本地安装产物： node_modules 如果状态仍然不一致，这通常是下一个候选项。
3. 从头重新安装： 运行 yarn install 再次运行并确认依赖图按预期解析。

如何确认缓存位置

如果你想直接检查或删除缓存目录，Yarn Classic 会提供路径：

yarn cache dir

当 CLI 命令似乎无法解决问题，或者你需要确认在共享或容器化环境中哪个用户账户拥有缓存目录时，这很有用。

在 Yarn Classic 1.22 中， yarn cache dir 指向缓存根目录下的版本文件夹（例如 v6 在默认 macOS ~/Library/Caches/Yarn 树中）。不带包名的完整 yarn cache clean 会删除该父级缓存根目录，而不仅仅是版本子目录。如果你将 cache-folder 设置为也存储非 Yarn 文件的路径，完整清理可能会删除它们。请使用专用的缓存根目录，并在清除缓存前检查 yarn cache dir 的父目录。

如果你正在使用较旧的工具链并试图保持本地设置的可预测性，这篇关于 逐步安装 Capacitor CLI 的指南 配合彻底重置依赖效果更佳。

手动检查缓存往往比盲目执行第二次清理命令更有价值。

对于 v1 项目，思路很简单：一个共享缓存、一条大范围清理命令，下次 install 会重新填充你删掉的内容。

Yarn Berry v2+ 的现代缓存管理

Yarn Berry 改变了这一局面。如果你习惯了 Yarn v1，最大的变化在于缓存清理不再只是“清空全局存储然后重试”。Berry 支持更精细的控制，一旦你明确要清理什么，这会很有用。

Berry 改变了缓存模型

在现代 Yarn 中，缓存行为与项目本身的关联更紧密。这更符合 Berry 的整体思路：项目级控制、Plug’n’Play，以及让依赖与 repo 并存，而不是放在单一的机器级全局缓存里。

这就是为什么旧建议可能会误导你。在 v1 上学会 Yarn 的队友，可能以为一条命令就能全局清除所有内容。但在 Berry 中，你需要按以下范围来思考： 范围.

如果你在移动端和 Web 端 pipeline 中处理不同的 build 输出，这种“作用域”思维同样适用于包管理之外。这项对比针对 不同类型的 build 是一个有用的提醒：环境假设往往会渗入调试。

在命令详情之前，先快速看个图解：

Berry 中真正重要的命令

现代 Yarn 文档 yarn cache clean 中的 当前 Yarn cache clean 命令参考。作用域取决于生效的 enableGlobalCache 值来自 yarn config get enableGlobalCache:

• 使用 enableGlobalCache: true （Yarn 4+ 默认）， yarn cache clean 清除 Yarn 直接使用的全局共享缓存。
• 使用 enableGlobalCache: false （Yarn 2 和 3 默认）， yarn cache clean 清除当前活动的缓存目录（默认 ./.yarn/cache，通常被提交以实现零安装；一个自定义的 cacheFolder 可能指向其他位置，也会被移除）。
• yarn cache clean --all 清除当前活动的缓存范围，并在启用时清除独立的镜像。使用 enableMirror: false时，其他项目的全局缓存可能仍然存在。使用 enableGlobalCache: true时，旧的项目本地 .yarn/cache 可能仍然存在。
• yarn cache clean --mirror 仅在存在独立镜像缓存时清除该镜像缓存。当 Yarn 已直接使用全局缓存时， --mirror 可能不会移除任何内容。

使用 --all 针对当前配置，使用 Berry 提供的最全面的清理方式，然后通过 yarn config get cacheFolder 检查该路径，若仍有残留文件。使用 --mirror 仅在确认项目使用镜像后执行。

决策点： 在 Berry 中，选错 scope 是缓存清理看似“无效”的主要原因之一。

这就是实际区别。Yarn Classic 默认范围很广，Berry 则从设计上就是显式的。

CI/CD 与 Docker 的 Yarn 缓存最佳实践

在 CI/CD 中，盲目清理 Yarn cache 通常是个错误。清理状态看似安全，但往往删掉的正是 pipeline 为了速度和可重复性所依赖的状态。

更有用的问题是： 你到底在缓存什么，又在恢复什么？

为什么在 pipeline 中清理缓存往往是错误做法

CircleCI 的一次讨论揭示了许多团队在实际项目中遇到的失败模式。清理 cache 并没能解决安装慢的问题，因为瓶颈不在于过时的包归档，而在于 fetch 和 link 行为、cache 目录不匹配以及 node_modules 缓存集合中缺失的路径，正如该 CircleCI Yarn caching 讨论帖中所述.

这一点很重要，因为 CI 系统经常把一个底层原因掩盖在模糊的症状背后：“install 慢”或“dependency 步骤不稳定”。开发者随后清理 cache、重新运行，却没有得到任何实质性的改善。

常见的 pipeline 错误包括：

• 缓存了错误的目录： restore 步骤完成了，但 Yarn 并没有使用恢复后的位置。
• 忽略工作区路径： 根依赖可能已还原，但工作区安装仍需重新链接。
• Docker 层构建顺序错误： 复制源 code 会使依赖层失效，导致每次都要重新安装包。

在 CI 中，配置不当导致的缓存未命中看起来非常像缓存损坏。

如果你在自动化环境中构建移动应用，发布工具也会在这里派上用场。团队通常会把 GitHub Actions 或 CircleCI 与分发和更新系统结合使用。在这个更大的工作流中，一个选择是 面向 Capacitor 应用的 Capgo CI/CD 配置，以及 推出 Capgo 云构建 用于远程原生构建，搭配你的包管理器和构建缓存策略。

更好的 CI 和 Docker 方案

要有意识地使用缓存失效，而不是凭感觉。

在 CI 中，可靠的模式如下：

1. 基于依赖状态的缓存： 将缓存键绑定到 yarn.lock 以及相关的 Yarn 配置文件。
2. 安装前恢复： 确保恢复的路径与该环境中 Yarn 将使用的路径一致。
3. 保持一致的安装： 在不可变环境中，使用强制校验 lockfile 正确性的安装模式。
4. 在真实变更时失效： Yarn 版本变更、lockfile 更新或缓存路径变更都是重建缓存的合理理由。

对于 Docker，原则类似：

• 先复制依赖清单： 尽可能将依赖安装层与应用源代码分离。
• 避免在镜像构建中进行不必要的清理： 在同一次构建中删除缓存，往往会破坏有用的层复用。
• 明确用户所有权： 由 root 创建的缓存目录可能会导致非 root 运行时用户后续安装失败。

简短的决策表很有帮助：

只有在确认陈旧缓存内容确实是问题根源时，才在 CI 中使用 Yarn clear cache。大多数情况下，解决办法是更好的缓存设计。

Yarn cache clean 故障排除

最令人沮丧的缓存 bug，是清理缓存后依然存在的那个。你执行了针对性清理并重新安装，但 Yarn 仍然拉取旧包。此时，你很容易怀疑 registry 出错，或者 lockfile 闹鬼了。

Yarn 中一个有记录的历史 issue 说明了原因。开发者报告称 yarn cache clean <package-name> 可能会在 cache/.tmp中留下旧副本，这意味着安装会一直使用陈旧版本，直到该临时目录被删除或执行完整清理，正如 Yarn 中关于陈旧缓存产物的 issue 中所述 .tmp.

当针对性清理后仍残留旧包时

道理很简单。 部分清理并不总是足够的。

如果你怀疑是版本过旧而非广泛损坏，请按此顺序操作：

• 从最明显的检查开始： 确认你正在调试预期的包版本和来源。
• 不要过度依赖针对特定包的清理： 定向清理可能会留下临时产物。
• 升级为完全清除缓存： 在 Classic 中，运行 yarn cache clean （不带包名），然后 yarn install。在 Berry 中，使用 yarn cache clean --all 以覆盖配置允许的最大范围。
• 手动检查临时缓存路径： 在旧版配置中， cache/.tmp 可能是缺失的一环。

当某个包持续解析到旧版产物时，在定向清理失败后，临时缓存文件通常是我首先检查的地方。

看似缓存问题的权限与环境问题

并非所有“缓存错误”都是缓存内容的问题。

在 Docker、多用户 Linux 系统或 CI runner 中，你可能会遇到权限错误，因为缓存目录的所有者与运行 Yarn 的进程用户不同。这种情况下，在修复所有权问题前，清理缓存也没用。实际做法是以正确的用户身份运行 Yarn，或在重新安装前修复目录所有权。

这类问题常常看起来像缓存过期，因为安装在不同环境中的失败情况并不一致。解决办法在运维层面，与包本身无关。

关于清理 Yarn 缓存的常见问题

yarn clear cache 的正确命令是什么？

Yarn 并不附带 yarn clear cache 子命令。文档中记录的命令是 yarn cache clean。在 Yarn Classic v1 中，它会清除用户目录下的全局缓存。在 Yarn Berry v2 及更高版本中，作用范围取决于标志和有效的 enableGlobalCache 来自 yarn config get enableGlobalCache.

如何在 Yarn Classic 和 Yarn Berry 中运行 yarn cache clean？

当 经典 v1，运行 yarn cache clean，然后 yarn install。使用以下命令检查路径： yarn cache dir。在 Berry，运行 yarn config get enableGlobalCache （Yarn 4+ 默认为 true；Yarn 2 和 3 默认为 false）。 yarn cache clean 会清除当前激活的缓存范围。使用 yarn cache clean --all 针对当前活动作用域，若启用镜像则包含镜像；但仍可能保留磁盘上的其他全局或项目缓存。请使用 --mirror 仅在存在独立镜像时使用。

清除 Yarn 缓存安全吗？

对于常规开发是安全的。清除操作会移除已下载的包归档，而不会删除您的应用源代码。下次安装可能需要更长时间。在 Classic 模式下， yarn cache dir 显示的是带版本号的缓存文件夹，但完整的 yarn cache clean 会移除父级缓存根目录。请检查该父目录，如果您自定义了配置，请使用专用的 cache-folder 。在 Berry 模式下，请在执行完整清理前运行 yarn config get cacheFolder 。 yarn cache clean 以及 yarn cache clean --all 会移除整个有效缓存目录。使用 enableGlobalCache: false时，该路径通常是 ./.yarn/cache，但自定义 cacheFolder 可以指向父级目录，例如 .yarn 并删除存储在该处的其他项目文件。当启用独立镜像时， yarn cache clean --all 还会移除位于 globalFolder下的缓存。运行 yarn config get globalFolder 在……之前 --all 如果该路径可能包含其他文件。将彻底清理视为调试步骤，而非日常维护。

何时应避免在 CI 或 Docker 中清除 Yarn 缓存？

当安装缓慢但 lockfile 正确时，请跳过例行的缓存清除。首先修复缓存键、恢复路径和 Docker 层顺序。仅在确认存在过期或损坏的包工件证据时才清除缓存，不要将其作为默认的重试步骤。

如何验证 Yarn 存储缓存的位置？

当 经典版 v1，运行 yarn cache dir. 开启 Berry，运行 yarn config get cacheFolder, yarn config get enableGlobalCache，以及 yarn config get globalFolder 当使用镜像或 yarn cache clean --all 时。请确认在 CI 和容器中运行 Yarn 的用户拥有这些目录的所有权。

为什么执行 yarn cache clean 后仍会残留旧包？

针对性清理可能会在临时文件夹（如 cache/.tmp ）中留下文件，这在旧版 Yarn 中尤为常见。在 Classic 版本中，请运行 yarn cache clean （不带包名），然后执行 yarn install。在 Berry 版本中，请使用 yarn cache clean --all，并删除 node_modules 如有需要，请重新安装，并检查临时路径，以防某个包仍解析到旧版本。

如果你的团队正在发布 Capacitor 应用，并且在依赖或构建问题后需要更干净的 release pipeline， Capgo 是一种无需等待应用商店审核就能交付 JavaScript 和资源更新的选择，同时让构建和 rollout 流程与包缓存排障分开。