你运行了 yarn install，但刚刚更新的依赖项仍然指向旧版本。或者你的笔记本电脑安装正常，CI 却在一次无害的 lockfile 变更后突然报错。又或者即使你“正在使用缓存”，Docker 重建依然极其缓慢。
通常这时人们会搜索 Yarn 清理缓存 并直接粘贴找到的第一个命令。
有时这有效，有时却毫无作用。原因很简单：Yarn 的缓存行为很大程度上取决于你正在运行哪个版本的 Yarn，以及... Yarn Classic v1 和 Yarn Berry v2+ 足以改变该用哪条命令和排查策略。
大多数指南只讲到 yarn cache clean。但这仅仅是个开始。关键在于缓存范围：你的项目使用的是本地缓存还是共享缓存，以及你的实际问题是否真的与缓存有关。在 CI 和 Docker 环境中，糟糕的缓存策略往往比过时的包归档带来的麻烦更多。
目录
- 构建失败？Yarn 缓存可能是罪魁祸首
- 何时以及为何要清理 Yarn 缓存
- 在 Yarn Classic v1 中清理缓存
- Yarn Berry v2+ 中的现代缓存管理
- CI/CD 与 Docker 中的 Yarn 缓存最佳实践
- 常见 Yarn 缓存错误排查
- 关于清理 Yarn 缓存的常见问题解答
构建失败？Yarn 缓存可能是罪魁祸首
这种场景你一定很熟悉：你升级了某个包，拉取了最新改动，然后再次运行 install。命令执行完成，但应用仍表现得像旧依赖还在。这时有人建议清理缓存，你开始怀疑这到底是真正的修复，还是只是玄学。
它可能是真正的修复，也可能只是干扰。
缓存问题通常以几种可预测的方式出现：本地包无法刷新；CI 拉取了意料之外的内容；或者即使 lockfile 显示一切匹配，新分支的表现也与主分支不同。如果你正在排查更广泛的 pipeline 不稳定问题，建议把缓存调试和更系统的构建审查结合起来，比如这篇关于 修复 Capacitor CI/CD pipeline 构建失败的指南.
实用原则： 把清理 Yarn 缓存当作诊断工具，而不是例行维护。
棘手的地方在于，Yarn 的缓存模型随着时间发生了变化。在旧项目中，缓存是全局共享的；而在新项目中，根据命令参数的不同，缓存清理可以是项目本地的、全局的，或者两者兼有。所以当队友说“直接清理 Yarn 缓存吧”时，你首先应该问的是： 是哪种 Yarn？
因此，有效的缓存修复始于对上下文的了解。是本地机器还是 CI runner？是 Yarn v1 还是 Berry？是共享缓存还是项目缓存？明确了这些，你的命令才会精准有效，而不是碰运气。
何时以及为何要清理 Yarn 缓存
当你遇到特定的故障模式时，清理 Yarn 缓存就非常有意义。它最实用的场景包括：移除过时的包产物、从损坏的下载状态中恢复，或者刻意擦除已存储的包以便让 Yarn 从头开始重新构建。
缓存出问题的症状
以下是一些典型的缓存清理场景：
- 依赖项无法更新： 你更改了版本或重新构建了本地包，但安装时仍然拉取旧的产物。
- 安装失败，而且像是状态问题： 一台机器可以正常工作，另一台却不行，且重复运行相同的命令始终得到相同的错误结果。
- 你需要释放本地磁盘空间： 这在开发机上比在短生命周期的 CI 环境中更重要。
其他情况只是看起来像缓存问题。如果你的 lockfile 意外变化、workspace 配置不一致，或者 Docker build 让错误的层失效，清理缓存并不能解决根本原因。做 app build 的团队经常在同时处理 native tooling、JavaScript 依赖和 plugin 更新时遇到这种情况。在这种情况下，这份关于 在 Capacitor 项目中管理依赖 的实用概览值得放在手边。
如果你的目标是更全面地清理机器，而不是排查 package 问题，系统级指南也能帮上忙。Mac 开发者如果想要 为 Mac 用户清理 app 缓存 经常会发现，package manager 只是存储占用情况的一部分。
何时不该使用 Yarn clear cache
不要把 Yarn clear cache 当作解决所有安装问题的首选方案。
有证据表明 package 状态陈旧或损坏时再用。如果问题更可能是以下情况，就别用：
| 场景 | 更好的第一步 |
|---|---|
| Lockfile 漂移 | 审核 yarn.lock 变更并一致地重新安装 |
| Workspace 解析问题 | 检查 workspace 配置与安装行为 |
| Docker 重建缓慢 | 检查 Layer 顺序与缓存持久化 |
| CI 环境不一致 | 确认实际恢复了哪些目录 |
如果安装出错是因为环境不对，那清缓存只会让下一次错误的安装更慢。
分清这一点能省下大量时间。很多白费的调试，都是因为把缓存当成了万能的重置按钮。
在 Yarn Classic v1 中清理缓存
Yarn Classic 的行为模式，正是许多开发者至今仍认为所有 Yarn 版本都具备的特性。它使用 全局缓存 存储在用户目录中，并且 yarn cache clean 会清除该共享缓存。Yarn Classic 的官方文档也是这样描述的，并指出缓存会在下次 yarn 或 yarn install 运行时重新填充。这种用户目录模型记录在 Yarn Classic 缓存 CLI 文档中.
该命令实际删除了什么
对于 Yarn v1，默认的清理命令非常直接：
yarn cache clean
该命令会擦除整个共享缓存，而不仅仅是当前项目。如果你在同一台机器上处理多个仓库，这一点至关重要。之后在任何一个仓库中进行 install，都可能需要重新获取包。
这种共享缓存设计是导致 Yarn v1 产生跨项目混淆行为的原因之一。全局缓存中的陈旧 artifact 可能会长期存在并影响不同的 repo，尤其是在涉及本地包开发时。
Yarn Classic 的常用操作流程如下：
- 首先运行 clean 命令：
yarn cache clean - 如有必要，删除本地安装产物：
node_modules当状态仍不一致时，这通常就是下一步要尝试的。 - 从零开始重新安装： 运行
yarn install再次运行并确认依赖图解析符合预期。
如何验证缓存路径
如果你想直接检查或删除缓存目录，Yarn Classic 会提供如下路径：
yarn cache dir
当 CLI 命令似乎无法解决问题，或者需要在共享或容器化环境中确认缓存目录归哪个用户账户所有时，这会很有用。
如果你在使用旧版工具链，并希望本地配置保持可预测，这篇分步指南将介绍 如何逐步安装 Capacitor CLI 配合彻底的依赖重置效果更佳。
手动检查缓存往往比盲目执行第二次清理命令更有价值。
对于 v1 项目，思路很简单：一个共享缓存，一个大范围清理命令，下次 install 会重新填充你删掉的内容。
Yarn Berry v2+ 中的现代缓存管理
Yarn Berry 改变了游戏规则。如果你习惯了 Yarn v1，最大的变化是缓存清理不再只是“抹掉全局 store 然后重试”。Berry 支持更精准的控制，一旦你明确了清理目标，这会非常有用。
Berry 改变了缓存模型
在现代 Yarn 中，缓存行为与项目本身联系得更紧密。这也符合 Berry 更宏观的思路：项目级控制、Plug’n’Play，以及依赖可以随 repo 存放、而不是放在单一机器级缓存中的工作流。
这就是为什么旧建议可能会误导你。在 v1 时代学习 Yarn 的队友，可能会以为一个命令就能全局清除所有内容。但在 Berry 中，你需要从以下维度思考： 作用域 (scope).
如果你在移动端和 Web 端 pipeline 中处理不同的 build 输出，这种“作用域”思维同样适用于包管理之外。可以看看这份 不同构建类型 (types of builds) 的对比 这很好地提醒我们：环境假设往往会渗入调试过程。
在进入命令细节前，先看个快速图解：
Berry 中重要的命令
现代 Yarn 文档 yarn cache clean 即删除 共享缓存文件，并在其中提供了两个重要开关 当前的 Yarn cache clean 命令参考:
yarn cache clean删除 Yarn 的共享缓存文件。yarn cache clean --mirror清除全局缓存，而非当前项目的本地缓存。yarn cache clean --all同时删除全局缓存文件和当前项目的本地缓存文件。
相比 Yarn v1，这能带来更有目的性的工作流。
| 目标 | 命令 |
|---|---|
| 清理默认的共享缓存作用域 | yarn cache clean |
| 针对全局镜像缓存 | yarn cache clean --mirror |
| 对本地和全局缓存文件进行彻底重置 | yarn cache clean --all |
使用 --all 当你想要实现“彻底重来”的效果时。使用 --mirror 当你确定问题出在全局缓存层，且不想清除项目中所有内容时。
决策点： 在 Berry 中，选择错误的作用域是导致缓存清理看起来“毫无作用”的主要原因之一。
这就是实际的区别。Yarn Classic 默认范围较广，而 Berry 在设计上更加明确。
适用于 CI/CD 和 Docker 的 Yarn 缓存最佳实践
在 CI/CD 中，盲目清理 Yarn cache 通常是个错误。这让人感觉安全，因为清除了状态，但往往会删掉 pipeline 为了保证速度和可重复性所依赖的状态。
更值得思考的问题是： 你到底在缓存什么，又在恢复什么？
为什么在 pipeline 中清理 cache 往往是错误的做法
CircleCI 的一次讨论揭示了许多团队在实际项目中遇到的失败模式。清理 cache 并没能解决安装慢的问题，因为瓶颈不在于过时的包归档，而在于 fetch 和 link 行为、cache 目录不匹配以及 node_modules 缓存集合中缺失的路径，正如那篇 CircleCI Yarn caching 讨论帖中所述.
这很重要，因为 CI 系统通常会将底层原因掩盖在一个模糊的症状之后：“install 慢”或“依赖步骤不稳定”。开发者随后清理 cache 并重新运行，却发现没有任何实质性的改善。
常见的 pipeline 错误包括：
- 缓存了错误的目录： restore 步骤已完成，但 Yarn 并未使用恢复后的路径。
- 忽略了 workspace 路径： 根目录依赖可能已恢复，但 workspace 的安装仍需重新链接。
- Docker 层构建顺序错误： 源码 code 的复制会导致依赖层失效，从而导致每次都要重新安装包。
在 CI 中，配置错误导致的缓存未命中（cache miss）看起来非常像缓存损坏。
如果你在自动化环境中构建移动应用，发布工具链也将发挥作用。团队通常会将 GitHub Actions 或 CircleCI 与分发及更新系统结合使用。在这种更广泛的工作流中，一个选择是 Capgo 为 Capacitor 应用提供的 CI/CD 设置，并配合你的包管理器和构建缓存策略。
更优的 CI 和 Docker 方案
有意识地使用缓存失效机制，而不是凭感觉。
对于 CI，一个可靠的模式如下：
- 基于依赖状态的缓存： 将缓存键绑定到
yarn.lock相关的 Yarn 配置文件。 - 安装前恢复： 确保恢复的路径与 Yarn 在该环境中使用的路径一致。
- 保持安装一致性： 在不可变环境中，请使用强制保证 lockfile 正确性的安装模式。
- 发生实际变更时失效： Yarn 版本变更、lockfile 更新或缓存路径变更，都是重建缓存的充分理由。
对于 Docker，原理也类似：
- 先复制依赖清单： 尽可能将依赖安装层与应用源码分开。
- 避免在镜像构建中进行不必要的清理： 在同一次构建中删除缓存，往往会破坏有用的层复用。
- 明确用户所有权： 由 root 创建的缓存目录，可能会导致非 root 运行时用户在后续安装时失败。
参考下表进行决策：
| 场景 | 优于以下方案 yarn cache clean |
|---|---|
| 恢复缓存后 CI 安装速度变慢 | 验证缓存路径和恢复顺序 |
| Workspaces 仍需大量重新链接 | 缓存相关的 workspace 安装产物 |
| Docker 重建时重新运行安装 | 围绕依赖文件重新调整层顺序 |
| 依赖变更后构建失败 | 使缓存键失效，然后进行全新构建 |
仅在确认陈旧缓存确实是问题所在时，才在 CI 中使用 Yarn clear cache。大多数情况下，更好的缓存设计才是根本解决方案。
常见 Yarn 缓存错误排查指南
最让人沮丧的缓存 Bug 是那种在清理缓存后依然存在的。你执行了针对性清理并重新安装，但 Yarn 还是拉取了旧包。这时，你很容易怀疑是 Registry 有误或者 lockfile 出问题了。
Yarn 中一个已记录的历史问题解释了原因。开发者反馈说 yarn cache clean <package-name> could leave an old copy behind in cache/.tmp, which meant installs kept using the stale version until that temporary directory was removed or a full cleanup was run, as discussed in Yarn 缓存残留导致的问题 .tmp.
当针对性清理后仍残留陈旧包时
教训很简单。 局部清理并不总是足够。
如果你怀疑是版本过旧而非大规模损坏，请按此顺序操作：
- 首先进行常规检查： 确认你正在调试的是预期的包版本和源码。
- 不要过度依赖针对特定包的清理： 定向清理可能会留下残留的临时文件。
- 升级为彻底清除缓存： 如果旧版本依然存在，请清理更广泛的缓存范围。
- 手动检查临时缓存路径： 在旧版配置中，
cache/.tmp可能是解决问题的关键。
当某个包一直解析到旧的构建产物时，在定向清理失败后，我通常会首先检查临时缓存文件。
看起来像缓存问题的权限或环境问题
并非所有的“缓存错误”都是缓存内容本身的问题。
在 Docker、多用户 Linux 系统或 CI runner 中，由于缓存目录的所有者与运行 Yarn 的进程用户不同，可能会导致权限失败。在这种情况下，除非修复所有权问题，否则清理缓存也无济于事。实际的做法是在重新安装之前，以正确的用户身份运行 Yarn，或者修复目录的所有权。
这类问题通常表现为缓存过期，因为安装过程在不同环境下会表现出不一致的失败。其解决方法属于运维层面，而非包本身的问题。
关于清理 Yarn 缓存的常见问题解答
清理 Yarn 缓存安全吗？
是的。在常规开发中，这是一个安全的操作，因为你删除的是缓存的包产物，而不是应用程序的源码。Yarn 可以在下次安装时重新获取所需内容。
代价是时间。清理缓存意味着下次安装可能需要下载或重新构建比平时更多的内容。
应该多久清理一次
仅在有必要时。
对于运行良好的项目，`yarn cache clean` 不应作为常规维护手段。如果你习惯性地将其加入每个工作流，会减慢本地安装速度并破坏 CI 缓存机制。仅在依赖项过期、安装看起来已损坏，或在调试期间需要刻意重置时使用它。
会影响生产构建吗
不会直接影响。清理本地或 CI 缓存并不会改变你已经提交的应用程序 code。
它真正改变的是准备构建的环境。如果你的生产 pipeline 依赖缓存的安装产物，清理它们可能让构建变慢，或暴露隐藏的可复现性问题。这在排障时很有用，但没理由就别往 release 脚本里塞。
最简单实用的规则是什么
针对问题，选择最小范围的清理操作。
本地调试时，先从 Yarn 在该项目中使用的缓存范围入手。CI 和 Docker 场景下，先修正缓存设计，再开始清空缓存。当针对特定包的清理不起作用时，先考虑临时产物或环境不匹配，再怀疑 Yarn 出了问题。
如果你的团队正在发布 Capacitor 应用，并且在遇到依赖或构建问题后需要更清爽的 release pipeline， Capgo 是无需等待应用商店审核即可交付 JavaScript 和资源更新的一种选择，同时让你的构建和发布流程与包缓存排障保持分离。
