你运行 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+中的现代缓存管理
- CI/CD和Docker中的Yarn缓存最佳实践
- 解决常见的Yarn缓存错误
- 关于清除Yarn缓存的常见问题
你的构建出错了，Yarn缓存可能是原因
一个熟悉的模式如下。您升级一个包，pull最新的更改，运行安装命令。命令完成，但应用程序仍然表现得像旧依赖项存在一样。然后有人建议清除缓存，现在你在想这是否是一个真正的解决方案还是只是迷信。
它可以是一个真正的解决方案。它也可以是一个分散。
缓存问题通常会以几个可预测的方式出现。一个本地包不会刷新。CI pull一些意外的内容。一个新分支的行为与主分支不同，尽管锁文件说应该匹配的内容。 如果你已经在追逐更广泛的管道不稳定性，帮助的是将缓存调试与更系统的构建审查结合起来，例如本指南 解决Capacitor CI/CD pipeline中的构建故障.
实用规则： 将 Yarn 清除缓存视为诊断工具，而不是维护习惯。
困难在于 Yarn 在不同时间点改变了其缓存模型。在较旧的项目中，缓存是共享的。 在新项目中，缓存清除可以是本地的、全局的或两者兼而有之，具体取决于命令标志。因此，当同事说“只需清除 Yarn 缓存”，首先应该问的问题是： 哪个 Yarn？
因此，一个好的缓存修复从上下文开始。 本地机器或 CI 运行器。 Yarn v1 或 Berry。 共享缓存或项目缓存。 一旦你知道了这一点，命令就变得精确而不是盲目了。
何时何处清除 Yarn 缓存
清除 Yarn 缓存在某些特定故障模式下有意义。它最有用的是当你需要移除陈旧的包裹艺术品、恢复从断开的下载状态或故意擦除存储的包裹以便 Yarn 从头开始重建时。
指向缓存问题的症状
有些情况是缓存的强烈候选者：
- 依赖项拒绝更新： You changed the version, or rebuilt a local package, but installs still pull an older artifact.
- 安装过程中出现了状态感知的问题： 一台机器可以正常工作，另一台机器却不能，重新运行相同的命令仍然会产生相同的错误结果。
- 您需要回收本地磁盘空间： 在开发机上比在短暂的CI环境中更为重要。
其他情况看起来像缓存问题，但实际上并非如此。如果您的lockfile意外发生了变化，工作区设置不一致，或者Docker构建错误地invalidate了某个层，清除缓存并不能解决根本问题。团队在处理app构建时经常遇到这种问题，他们需要处理native工具、JavaScript依赖项和插件更新。因此，在__CAPGO_KEEP_0__项目中管理依赖项的实用指南值得保存。 managing dependencies in Capacitor projects 何时不应使用Yarn清除缓存
何时不应使用Yarn清除缓存 何时不应使用Yarn清除缓存 何时不应使用Yarn清除缓存
何时不应使用Yarn清除缓存
不要将清除 Yarn 缓存作为每次安装问题的第一反应。
在有证据表明包状态过时或损坏时使用它。跳过它，问题更可能是：
| 情况 | 更好的第一步 |
|---|---|
| 锁文件漂移 | 查看更改和一致性重新安装 yarn.lock 工作区解析问题 |
| 检查工作区配置和安装行为 | Docker 重建缓慢 |
| 查看层顺序和缓存持久性 | CI 不匹配 |
| __CAPGO_KEEP_0__ | 验证哪些目录实际上被恢复 |
如果安装错误是因为环境错误，清除缓存只会使下一次错误安装变慢。
这种区别节省了时间。大量的浪费调试时间来自于将缓存当作魔法重置按钮。
Yarn Classic v1 中的清除缓存
Yarn Classic 的行为与许多开发者仍然假设所有 Yarn 版本的行为相同。它使用 全局缓存 在用户目录中，并 yarn cache clean 清除该共享缓存。Yarn Classic 的文档描述了它的方式，并注意到缓存在下一次 yarn 或 yarn install 在用户目录模型中运行的文档中描述的下一个 Yarn Classic 缓存CLI文档.
实际上该命令删除的是什么
对于 Yarn v1，清理命令的默认设置是直接的：
yarn cache clean
该命令清除的是共享缓存，而不是当前项目。 如果您在同一台机器上工作于多个仓库，那么这就很重要。 在任何一个仓库中进行下一次安装可能需要重新获取包。
这种共享缓存设计是 Yarn v1 可能会产生混淆的跨项目行为的原因之一。 在全局缓存中存活的陈旧 artifact 可能会在很长时间内影响不同的仓库，尤其是在涉及本地包开发的情况下。
对于 Yarn Classic，通常的实践顺序如下：
- 首先运行清理命令：
yarn cache clean - 如果需要，清除本地安装 artifact：
node_modules当状态仍然不一致时，"yarn cache clean" - 重新从头开始安装： 再次运行
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中，你需要以 __CAPGO_KEEP_0__.
如果你处理不同于移动和web管道的构建输出，那么同样的范围思维也适用于外部包管理。 这是一个有用的提示，说明环境假设会渗透到调试中。 在命令细节之前，以下是一个快速的可视化解释：
在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 路径，正如在那个 CircleCI Yarn 缓存线程中描述的.
因为CI系统经常会将潜在的原因隐藏在一个模糊的症状后面，如“安装慢”或“依赖步骤不稳定”。开发者们会清除缓存，重新运行，但没有任何有意义的改进。
常见的管道错误包括：
- 错误地缓存目录： 恢复步骤完成，但Yarn并没有使用恢复的位置。
- 忽略工作区路径： 根依赖项可能会恢复，而工作区安装工作仍然需要重新链接。
- 在CI中，缓存失效由坏的配置引起，看起来和缓存损坏一样。 如果您在自动化环境中构建移动应用程序，这也就是发布工具进入的场景。团队经常结合code Actions或CircleCI与发布和更新系统。一个选项是在更广泛的工作流中使用
__CAPGO_KEEP_0__的CI/CD设置__CAPGO_KEEP_1__应用程序
If you’re building mobile apps in automated environments, this is also where release tooling enters the picture. Teams often combine GitHub Actions or CircleCI with distribution and update systems. One option in that broader workflow is Capgo’s CI/CD setup for Capacitor apps__CAPGO_KEEP_1__
A better CI and Docker approach
在使用缓存时，应有意为之，而不是感情用事。
对于 CI，一个可靠的模式如下：
- 基于依赖状态的缓存： 将缓存键与
yarn.lock和相关的 Yarn 配置文件绑定。 - 在安装之前恢复： 确保恢复的路径与 Yarn 在该环境中使用的路径匹配。
- 一致的安装： 在不可变的设置中，使用强制锁文件正确性的安装模式。
- 在真实变化时失效： Yarn 版本变化、锁文件更新或缓存路径变化都是重建缓存的好理由。
对于 Docker 来说，原则是类似的：
- 首先复制依赖项清单： 尽可能将依赖项安装层与应用程序源分开：
- 避免在镜像构建中进行不必要的清理： 在同一构建中删除缓存往往会移除有用的层重用：
- 对用户所有权进行明确说明： 由 root 创建的缓存目录可能会在非 root 运行时用户安装时造成后续失败：
一个简短的决策表会有所帮助：
| 场景 | 比 yarn cache clean |
|---|---|
| CI 安装在恢复后会变慢 | 验证缓存路径和恢复顺序 |
| 工作区仍然频繁重新链接 | 缓存相关工作区安装的艺术品 |
| docker重建重新安装 | 依赖文件的层次重新排序 |
| 依赖项变化后只有一次坏的构建 | 缓存键无效，然后重新构建干净 |
在CI中只在确认缓存内容过时是实际问题时使用Yarn清除缓存。通常，解决方案是更好的缓存设计。
解决常见的Yarn缓存错误
最令人沮丧的缓存错误是那些在清除缓存后仍然存在的错误。您运行一个目标清洁，重新安装，并且Yarn仍然拉取旧的包。到那时，人们很容易假设注册表有问题或锁文件被诅咒。
Yarn的一个文档历史问题解释了为什么会发生这种情况。开发人员报告说 yarn cache clean <package-name> 可能会留下一个旧副本在 cache/.tmp,这意味着安装一直使用过时的版本，直到临时目录被删除或进行了全面的清理，正如在讨论中提到的那样 关于Yarn缓存中陈旧的工件问题 .tmp.
即使进行了针对性的清理，陈旧的包依然留在后面
这就是教训 部分清理并不总是足够
如果你怀疑是版本陈旧而不是广泛的损坏，使用以下顺序
- 首先进行明显的检查 确认你正在调试的包版本和源是预期的
- 不要太信任包级别的清理 针对性的清理可能会留下临时工件
- 升级到全缓存擦除 如果陈旧的版本仍然存在，清理更广泛的缓存范围
- 手动检查临时缓存路径 In older setups,
cache/.tmp可能是缺失的关键部分。
当一个包始终解析到旧的工件时，临时缓存文件通常是首先检查的位置，尤其是在目标清理失败后。
看起来像缓存问题的权限和环境问题
并不是每个“缓存错误”都是缓存内容问题。
在 Docker、多用户 Linux 系统或 CI 运行器中，您可能会遇到权限失败，因为缓存目录由一个不同的用户拥有，而 Yarn 运行的用户不同。在这种情况下，清除缓存不会有帮助，直到拥有权问题得到解决。实践方法是以正确用户运行 Yarn，或者在重新安装之前修复目录拥有权。
这种问题通常表现为陈旧的缓存，因为安装在不同环境中不一致。解决方案是操作性的，而不是与包相关的。
关于清除 Yarn 缓存的常见问题
清除 Yarn 缓存是否安全
是的。在正常开发中，这是一个安全的操作，因为您正在删除缓存的包工件，而不是删除应用程序源代码。Yarn 可以在下一次安装时重新获取所需的内容。
这种做法的权衡是时间。清除缓存意味着下一次安装可能需要下载或重建更多内容。
应该多久清除一次
只有当你有一个合理的理由时才会发生。
Yarn 清除缓存不应该成为健康项目的常规维护。 如果你将其纳入到每个工作流程中，习惯性地使用它，你会减慢本地安装速度并破坏 CI 缓存。 只有在依赖项过时、安装看起来被破坏或你需要故意重置调试时才使用它。
会影响生产构建吗
Not directly. Clearing your local or CI cache doesn’t change the application code you’ve committed.
它改变的是准备构建的环境。 如果你的生产管道依赖于缓存的安装艺术品，清除它们可能会使构建速度变慢或暴露隐藏的可重复性问题。 这在调试时很有用，但在没有理由的情况下将其添加到发布脚本中并不是什么好主意。
遵循最简单的实用规则
只使用匹配问题的最小清理。
对于本地调试，使用 Yarn 在该项目中使用的缓存范围开始。 对于 CI 和 Docker，修复缓存设计之前不要开始清除缓存。 当一个包特定的清理不起作用时，假设临时文件或环境不匹配，而不是假设 Yarn 是有问题的。
如果你的团队发布 Capacitor 应用程序并需要在依赖项或构建问题之后清洁的发布管道 Capgo 是将 JavaScript 和资产更新交付到商店而不等待审查的方法，同时保持你的构建和发布过程与包缓存调试分开。
