您运行 yarn install, 依赖项更新后，您的依赖项仍然解析到旧的构建中。 或者您的笔记本电脑安装正常，而CI突然在无害的锁文件更改后失败。 或者Docker重建拖延，尽管您正在“使用缓存”。
通常在这种情况下，人们会搜索 Yarn清除缓存 并粘贴他们找到的第一个命令。
有时这有效。有时这解决不了问题。原因很简单：Yarn的缓存行为取决于您正在运行的Yarn版本， Yarn Classic v1 和 Yarn Berry v2+ 之间的差异足够大，以至于改变了正确的命令和正确的故障排除策略。
大多数指南都会停在 yarn cache clean那才是开始。真正重要的是缓存范围，项目是否使用本地缓存还是共享缓存，以及你真正遇到的问题是否就是缓存问题。 在CI和Docker中，缓存策略不当往往比陈旧的包存档更让人头疼。
目录
- 你的构建出现问题，Yarn缓存可能是原因
- 何时何时清除Yarn缓存
- 清除Yarn Classic v1中的缓存
- Yarn Berry v2+中的现代缓存管理
- Yarn 缓存最佳实践：CI/CD 和 Docker
- 解决常见 Yarn 缓存错误
- 关于清除 Yarn 缓存的常见问题
Your Build Is Broken and Yarn Cache Might Be the Culprit
一个熟悉的模式看起来像这样。您更新一个包，pull最新的更改，重新运行安装命令。命令完成，但应用程序仍然表现得像旧的依赖项存在一样。然后有人建议清除缓存，结果您开始怀疑这是否是一个真正的解决方案还是只是迷信。
它可能是一个真正的解决方案。它也可能是一个分散的注意力。
缓存问题通常会以几个可预测的方式出现。一个本地包不会更新。CI拉取了一个意外的内容。一个新分支的行为与主分支不同，尽管锁文件说应该匹配。您已经在追踪更广泛的管道不稳定性时，帮助您将缓存调试与更系统的构建审查结合起来，例如在 修复Capacitor CI/CD管道中的构建故障指南.
实践规则： 将Yarn清除缓存作为一个诊断工具，而不是一个维护仪式。
困难的部分是Yarn在时间上改变了其缓存模型。在旧项目中，缓存是共享的。新项目中，缓存清除可以是本地的、全局的，或者两者都取决于命令标志。因此，当同事说“只需清除Yarn缓存”，第一个问题应该是： 哪个Yarn？
因此，一个好的缓存修复始于背景。机器或CI运行器。Yarn v1或Berry。共享缓存或项目缓存。您知道了这一点，命令就变得精确而不是盲目。
何时何地清除Yarn缓存
清除 Yarn 缓存在你有特定的故障模式时是有意义的。它在你需要移除陈旧的包裹艺术品、恢复从断点下载状态、或故意擦除存储的包裹以便 Yarn 从头开始重建时最有用。
指向缓存问题的症状
有些情况是缓存的强烈候选者：
- 一个依赖项拒绝更新： 你改变了版本，或者重建了一个本地包，但安装仍然拉取一个旧的艺术品。
- 安装失败以一种感觉有状态的方式： 一个机器可以工作，另一个不能，重新运行相同的命令会不断地重现相同的坏结果。
- 你需要回收本地磁盘空间： 这在开发者机器上比在短暂的 CI 环境中更重要。
其他情况看起来像缓存问题，但并不是。 如果你的锁文件意外改变了、如果一个工作区设置不一致、或者如果一个 Docker 构建无效地invalidate了一个错误的层，清除缓存就不会解决根本问题。 团队在处理应用程序构建时经常遇到这个问题，而他们在处理原生工具、JavaScript 依赖项和插件更新时要处理很多东西。 在这种情况下，这个实用的概述是关于 管理依赖项在 Capacitor 项目中的概述 __CAPGO_KEEP_0__.
如果您的目标是更广泛的机器清理而不是包管理器调试，系统级别的指南也可以提供帮助。想要为 Mac 用户清理应用程序缓存的 Mac 开发者 常常发现，包管理器只是存储的图景中的一部分。 何时不应该使用 Yarn 清除缓存
不要将 Yarn 清除缓存作为每个安装问题的第一反应。
在有证据表明存在陈旧或损坏的包状态时使用它。跳过它，当问题更可能是：
情况
| 更好的第一步 | 锁文件漂移 |
|---|---|
| 查看 | 更改并重新安装一致 yarn.lock When not to reach for Yarn clear cache |
| 工作区解析问题 | 检查工作区配置和安装行为 |
| Docker重建缓慢 | 查看层次顺序和缓存持久性 |
| CI不匹配 | 验证实际恢复的目录 |
如果安装错误是因为环境错误，清除缓存只会使下一次错误安装更慢。
这项区分节省了时间。大量的浪费调试时间来自于将缓存当作魔法重置按钮。
清除Yarn Classic v1缓存
Yarn Classic的行为与许多开发者仍然假设所有Yarn版本的行为相同。它使用 全局缓存 在用户目录中， yarn cache clean 清除共享缓存。 Yarn Classic 的文档描述了它的方式，并指出缓存在下一次重新加载。 yarn 或 yarn install 在用户目录模型中运行的文档 Yarn Classic 缓存 CLI 文档.
命令实际上删除了什么
对于 Yarn v1，清理命令的默认设置是直接的：
yarn cache clean
该命令清除了共享缓存，而不是当前项目。 如果您在同一台机器上工作多个仓库，情况就很重要了。 在任何仓库中下一次安装可能需要重新获取包。
共享缓存设计是 Yarn v1 可能会产生混淆的跨项目行为的原因之一。 在全局缓存中存活的陈旧艺术品可能会持续很长时间，影响不同的仓库，尤其是在涉及本地包开发的场景下。
Yarn Classic 的实际顺序通常如下：
- 首先运行清理命令：
yarn cache clean - 如果需要，请删除本地安装的艺术品：
node_modules当状态仍然不一致时，__CAPGO_KEEP_0__通常是下一个候选者。 - 重新安装： 重新
yarn install再次确认依赖图解析为预期结果。
如何验证缓存位置
当您想要直接检查或删除缓存目录时，Yarn Classic会给您路径：
yarn cache dir
这在CLI命令看起来似乎无法解决问题时很有用，或者在您需要在共享或容器化环境中确认哪个用户帐户拥有缓存目录时。
如果您正在使用较旧的工具链并且试图保持本地设置可预测，这个关于 一步一步安装Capacitor CLI的教程 与清洁依赖重置相配得很好。
手动缓存检查通常比第二次盲目清除命令更有价值。
对于v1项目，思维模型很简单。一个共享缓存，一个广泛的清除命令，下一个安装重新填充您删除的内容。
现代 Yarn Berry v2+ 缓存管理
Yarn Berry 改变了对话。 如果您习惯于使用 Yarn v1，最大调整是缓存清除不再仅仅是“清空全局存储并尝试再次”。 Berry 支持更精确的控制，这对于您了解目标后是有用的。
Berry 改变了缓存模型
在现代 Yarn 中，缓存行为与项目本身更密切相关。这符合 Berry 更广泛的方法，即项目级控制、插件式编程和工作流程，其中依赖项可以与仓库一起存活，而不是在单个机器级缓存模型中。
因此，旧的建议可能会误导您。 一个在 v1 上学习 Yarn 的同事可能会期望一个命令来清除全球的所有内容。在 Berry 中，您需要以 范围.
如果您处理不同于移动和 web pipeline 的构建输出，那么同样的范围思维在包管理之外也适用。 这个 构建类型 的比较是一个有用的提醒，环境假设往往会渗透到调试中。
以下是一个快速的可视化解释，之后是命令详细信息：
Berry 中的关键命令
现代 Yarn 文档 yarn cache clean 作为移除 清除共享缓存文件和它暴露了两个重要 switch 在 当前 Yarn 缓存清理命令参考:
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是设计为明确的。
Yarn缓存最佳实践：CI/CD和Docker
在CI/CD中，盲目清除Yarn缓存通常是一个错误。它感觉安全，因为它移除了状态，但它经常移除了您的管道依赖于速度和可重复性的状态。
更有用的问题是： 您缓存的是什么，且您恢复的是什么？
为什么在管道中清除缓存往往是错误的选择
一个CircleCI讨论捕捉到了许多团队在实际项目中遇到的失败模式。缓慢的安装并没有通过清除缓存来解决，因为瓶颈并不是陈旧的包存档，而是fetch和link行为、缓存目录不匹配以及缓存集中的缺失 node_modules paths 在那篇.
CircleCI Yarn缓存线程
这很重要，因为CI系统往往会将潜在原因隐藏在一个模糊的症状后面：“安装速度慢”或“依赖步骤不稳定”。开发人员然后清除缓存，重新运行，并没有获得任何有意义的改进
- 常见的管道错误包括： 缓存错误的目录：
- 恢复步骤完成，但Yarn并没有使用恢复的位置 忽略工作区路径：
- 根依赖项可能会恢复，而工作区安装工作仍然需要重新链接 A source code copy invalidates the dependency layer, so package installation reruns every time.
在 CI 中，由于配置错误导致的缓存失效看起来与缓存损坏的缓存一样。
如果您在自动化环境中构建移动应用程序，这也就是发布工具进入的场景。团队经常将 GitHub Actions 或 CircleCI 与发布和更新系统结合起来。其中一个选项是在更广泛的工作流中使用 Capgo’s CI/CD setup for Capacitor apps，与您的包管理器和构建缓存策略一起使用。
更好的 CI 和 Docker 方法
故意使用缓存失效，而不是情绪化地使用它。
对于 CI，一个可靠的模式如下：
- 基于依赖项状态的缓存： 将缓存键绑定到
yarn.lock和相关的 Yarn 配置文件。 - 在安装之前恢复： 确保恢复的路径与Yarn在该环境中使用的路径匹配。
- 一致性安装: 在不可变的设置中，使用强制锁文件正确性的安装模式。
- 在实际变化时失效: Yarn版本更改、锁文件更新或缓存路径更改是重建缓存的好理由。
对于Docker，原则是类似的:
- 首先复制依赖项清单: 在可能的情况下，将依赖项安装层与应用程序源代码分开。
- 避免在镜像构建中进行不必要的清理: 在同一构建中删除缓存通常会移除有用的层重用。
- 明确用户所有权: 由root创建的缓存目录可能会在后续的非root运行时用户安装中造成故障。
一个简短的决策表有助于：
| 场景 | 比起 yarn cache clean |
|---|---|
| CI安装缓慢后恢复 | 验证缓存路径和恢复顺序 |
| 工作区仍然重链接 | 缓存相关工作区安装的艺术 |
| Docker重建重新安装 | 重新排列依赖文件的层 |
| 依赖项更改后只有一次坏的构建 | 清除缓存键，然后重新构建干净 |
仅在确认陈旧缓存内容是实际问题时，在CI中使用Yarn清除缓存。大多数时候，解决方案是更好的缓存设计。
Troubleshooting Common Yarn Cache Errors
The most frustrating cache bug is the one that survives a cache clean. You run a targeted cleanup, reinstall, and Yarn still pulls the old package. At that point, it’s tempting to assume the registry is wrong or the lockfile is haunted.
A documented historical issue in Yarn shows why that happens. Developers reported that 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 the Yarn issue about stale cache artifacts in .tmp.
When a targeted clean still leaves stale packages behind
The lesson is simple. Partial clean is not always enough.
If you suspect version staleness rather than broad corruption, use this order:
- Start with the obvious check: Confirm you’re debugging the expected package version and source.
- Don’t trust a package-specific clean too much： Targeted cleanup 可能会留下临时文件：
- Escalate to a full cache wipe： 如果旧版本仍然存在，清理更广泛的缓存范围：
- 手动检查临时缓存路径： 在旧的设置中，
cache/.tmp可能是缺失的部分：
当一个包始终解析到旧的工件时，临时缓存文件往往是首先要检查的位置，尤其是在目标清理失败后。
看起来像缓存问题的权限和环境问题
并不是每个“缓存错误”都是缓存内容的问题：
在 Docker、多用户 Linux 系统或 CI 运行器中，可能会遇到权限失败，因为缓存目录由一个不同的用户拥有，而 Yarn 运行的用户不同。在这种情况下，清除缓存不会有帮助，直到拥有权问题得到解决。实际的解决方案是以正确的用户身份运行 Yarn，或者在重新安装之前修复目录拥有权。
这种问题通常表现为不一致的环境安装失败。解决方案是操作性问题，而不是包相关问题。
关于清除Yarn缓存的常见问题
清除Yarn缓存是否安全
是的。在正常开发中，这是一个安全的操作，因为你正在删除缓存的包依赖项，而不是删除应用程序源码。Yarn可以在下一次安装时重新获取所需的内容。
清除缓存的代价是时间。一个干净的缓存意味着下一次安装可能需要下载或重建更多内容。
应该多频繁地清除缓存
只有当你有一个原因时。
Yarn清除缓存不应该成为一个健康项目的例行维护。如果你将其放入每个工作流程中，会减慢本地安装速度并破坏CI缓存。使用它时，依赖项过时、安装看起来有问题，或者你需要在调试过程中进行有意的重置时。
会影响生产构建吗
不会直接影响。清除本地或CI缓存不会改变你提交的应用程序code。
它会改变的是准备构建的环境。如果你的生产流水线依赖于缓存的安装依赖项，清除它们可能会使构建速度变慢或暴露隐藏的可重复性问题。这个过程在调试时很有用，但不应该在发布脚本中随意添加。
什么是最简单的实践规则
使用最小的清理来匹配问题。
对于本地调试，使用 Yarn 在该项目中使用的缓存范围开始。对于 CI 和 Docker，修复缓存设计之前开始清除缓存。并且，当一个包特定的清洁不起作用时，假设临时文件或环境不匹配之前假设 Yarn 是破损的。
如果您的团队部署 Capacitor 应用程序并需要在依赖关系或构建问题之后清洁的发布管道， Capgo 是将 JavaScript 和资产更新交付而不必等待商店审查的选项，同时保持您的构建和发布过程与包缓存调试分开。
