How to Yarn Clear Cache: A Guide for V1, Berry, and CI/CD yarn installYou run a project, and the dependency you just updated still resolves to the old build. Or your laptop installs fine while CI suddenly fails after a harmless lockfile change. Or Docker rebuilds drag on, even though you’re “using cache.”
那時候通常有人會搜尋 清空Yarn緩存 並將找到的第一個命令貼上。
有時候這樣做有效果。有時候這樣做什麼都沒有改善。原因很簡單：Yarn緩存行為取決於你正在運行的Yarn版本，以及 Yarn Classic v1 和 Yarn Berry v2+ 之間的差異足以改變正確的命令和正確的排除策略。
大多數指南只到這裡就停止了。這才是開始。 yarn cache clean關鍵在於緩存範圍、你的項目是否使用本地緩存或共享緩存，以及你的真正問題是否與緩存有關。
在CI和Docker中，緩存策略不當往往會導致比過期的套件檔案更大的痛苦。
- 目錄
- 当和为什么清除Yarn缓存
- 清除Yarn Classic v1中的缓存
- Yarn Berry v2+中的现代缓存管理
- Yarn缓存最佳实践（CI/CD和Docker）
- 解决常见的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 install并确认依赖图像解析为期望的结果。
如何验证缓存位置
当您想要直接检查或删除缓存目录时，Yarn Classic会给您路径：
yarn cache dir
这对解决问题特别有用，尤其是当CLI命令似乎无法解决问题时，或者您需要在共享或容器化环境中确认缓存目录的用户账户时。
如果您正在使用较旧的工具链并且试图保持本地设置的可预测性，这个关于 安装Capacitor CLI的逐步指南 与清洁依赖项重置相配得很好。
手动检查缓存通常比第二次盲目清除命令更有价值。
对于v1项目，思维模型很简单。一个共享缓存，一个广泛的清除命令，下一个安装会重新填充您删除的内容。
Yarn Berry v2+中的现代缓存管理
Yarn Berry改变了对话。如果您习惯于使用Yarn v1，最大调整就是缓存清除不再仅仅是“清除全局存储并尝试再次安装”。Berry支持更精确的控制，这对您了解自己要目标后是有用的。
Berry改变了缓存模型
在现代Yarn中，缓存行为与项目本身更密切相关。这符合Berry更广泛的项目级控制、插件式玩法和依赖项可以与仓库一起存活，而不是存储在单个机器级缓存模型中的工作流程。
所以老的建议可能会误导你。一个学习了v1 Yarn的团队成员可能会期望一个命令可以清除所有全局的内容。在Berry中，你需要以 scope.
的思维方式来思考。如果你处理不同的移动和web管道的构建输出，那么同样的思维方式也适用于外部的包管理。 types of builds 的比较是一个有用的提示，环境假设往往会渗透到调试中。
下面是一个快速的可视化解释，之后是命令详细信息：
Berry中的重要命令
现代Yarn文档 yarn cache clean 中关于 as removing共享缓存文件 的说明，Berry还暴露了两个重要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 当你知道问题出在全局缓存层并且不想清除项目中的所有内容时使用。
Decision point: 在Berry中，选择错误的范围是缓存清除看起来“什么都没做”的主要原因之一。
那就是实用的区别。Yarn Classic是默认广泛的。Berry是设计为明确的。
Yarn Cache最佳实践：CI/CD和Docker
在CI/CD中，盲目清除Yarn缓存通常是一个错误。它感觉安全，因为它移除了状态，但它经常移除了速度和可重复性的状态，pipeline依赖的状态。
更有用的问题是： 你缓存的是什么，恢复的是什么？
为什么在管道中清除缓存通常是一个错误的决定
一个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__
一个更好的CI和Docker方法
谨慎使用缓存失效，而不是情绪化地失效。
对于CI，一个可靠的模式如下：
- 基于依赖项状态的缓存： 将缓存键绑定到
yarn.lock和相关的Yarn配置文件中。 - 在安装之前恢复： 确保恢复的路径与Yarn在该环境中使用的路径匹配。
- 一致地安装： 在不可变的设置中，使用强制锁文件正确性的安装模式。
- 在真实的变化时失效： Yarn版本更改、锁文件更新或缓存路径更改是重建缓存的好理由。
For Docker, the principles are similar:
- 首先复制依赖项清单： 尽可能将依赖项安装层与应用程序源代码分开。
- 避免在镜像构建中进行不必要的清理： 在同一构建中删除缓存通常会移除有用的层重用。
- 明确用户所有权： 由 root 创建的缓存目录可能会在非 root 运行时用户安装时导致后续失败。
一个简短的决策表格有帮助：
| 场景 | 比 yarn cache clean |
|---|---|
| CI 安装缓慢后恢复 | 验证缓存路径和恢复顺序 |
| Workspaces仍然频繁重新链接 | 缓存相关的工作空间安装文件 |
| Docker重建重新安装 | 依赖文件的层次重新排序 |
| 依赖项变化后只有一次构建失败 | invalidate缓存键，然后重新构建干净 |
在CI中只在确认缓存内容过时是实际问题时使用Yarn清除缓存。通常，解决方案是更好的缓存设计。
Yarn缓存常见错误的故障排除
最令人沮丧的缓存错误是那些在清除缓存后仍然存在的错误。您运行一个目标清洁，重新安装，并且Yarn仍然从旧包中拉取。到那时，人们很容易假设注册表是错误的或锁文件是被诅咒的。
Yarn中有一个文档历史问题，解释了为什么会这样发生。开发人员报告说 yarn cache clean <package-name> 可能会留下一个旧副本在 cache/.tmp，这意味着安装一直使用过时的版本，直到临时目录被删除或进行了全面的清洁，正如在中讨论的那样， Yarn有关陈旧缓存物件的问题在 .tmp.
即使针对性清理仍然留下陈旧的包裹后
这就是教训。 部分清理并不总是足够的。
如果您怀疑版本陈旧而不是广泛的腐败，使用以下顺序：
- 首先进行明显的检查： 确认您正在调试的包裹版本和源是预期的。
- 不要对包裹特定的清理太有信心： 针对性清理可能会留下暂时的物件后果。
- 升级到全缓存擦除： 如果陈旧的版本仍然存在，清理更广泛的缓存范围。
- 手动检查临时缓存路径： In older setups,
cache/.tmp可能是缺失的关键部分。
When a package keeps resolving to an old artifact, temporary cache files are often the first place I’d inspect after a failed targeted clean.
看起来像缓存问题的权限和环境问题
并不是每个“缓存错误”都是缓存内容问题。
In Docker, multi-user Linux systems, or CI runners, you can hit permission failures because the cache directory is owned by a different user than the process running Yarn. In that case, clearing cache won’t help until the ownership problem is fixed. The practical move is to run Yarn as the correct user, or repair directory ownership before reinstalling.
这种问题通常表现为陈旧的缓存，因为在不同环境中安装失败不一致。解决方案是操作性的，而不是与包相关的。
Frequently Asked Questions About Clearing the Yarn Cache
清除 Yarn 缓存的常见问题
Is it safe to clear the Yarn cache
是的。在正常开发中，这是一个安全的操作，因为你是删除了缓存的包裹艺术品，而不是删除你的应用程序源代码。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 和资产更新交付到商店而不必等待商店审查的选项，同时保持你的构建和发布过程与包缓存调试分开。
