写这篇东西的起因其实挺简单。前端项目里一堆依赖要管npm 用着用着就开始嫌它慢尤其是在老项目里一次npm install能把人等得没脾气。后来听同行提到 Yarn谷歌一搜跳出来的第一条偏偏是How to install Yarn这种英文教程看着头大。问了几个同事说法还不一样有人让你直接npm install -g yarn有人让你用 Corepack还有人让你去官网下安装包。到底哪个是对的哪个适合自己这篇文章就把 Yarn 从下载到落地能用整个过程掰开揉碎讲清楚。不管你是刚接触前端的新手还是想升级构建工具链的老手只要按着下面的路径走基本十分钟内能把 Yarn 跑起来并且知道跑起来之后下一步该干什么。1. Yarn 到底解决了什么为什么前端人绕不开它在聊安装之前得先搞清楚我们要装的东西到底是什么货色。Yarn 是一款 JavaScript 包管理器和 npm 在职能上高度重叠——负责下载依赖、管理依赖版本、锁定依赖树、跑脚本。但当年 Yarn 能火起来最核心的原因是它抓住了 npm 的痛点慢。npm 早期的安装策略是串行执行而且没有全局缓存的概念一个不存在的包要反复去远程仓库拉取。不够确定性。同一份 package.json在不同机器上安装出来的依赖树偶尔不一致经典的我这跑得好好的到他那就不行。安装过程不透明。卡在某个依赖上半天没动静你并不知道是哪一步出了问题。Yarn 当初对这些痛点几乎是一击致命引入并行安装、引入离线缓存离线也能装依赖、引入yarn.lock锁文件保证任何人在任何时间安装依赖结果完全一致。1.1 Yarn 和 npm 的本质差异如果你已经是 npm 老用户关心的是 Yarn 凭什么值得换列表对比最直观维度npmYarn安装速度较慢串行为主较快并行下载锁文件package-lock.jsonyarn.lock离线缓存有但日常使用感知弱设计上强依赖缓存效果显著工作区支持但配置繁琐原生支持 monorepo 友好安全校验完整性校验细粒度一般默认校验包完整性输出可读性信息冗长日志相对简洁这里不吹 Yarn 一定碾压 npm实际上 npm 在 5.x 之后也做了大量优化现在的 npm 并没有传说中那么不堪。但 Yarn 在很多团队里成为默认选择确实有它的道理尤其在 monorepo、自动化流水线、大型依赖树的场景下优势相当明显。1.2 Yarn Classic 和 Yarn Berry 是什么关系搜 Yarn 安装教程时你大概率会看到两个概念Yarn Classic 和 Yarn Berry。这俩不是竞品是 Yarn 的版本代际Yarn Classic即 Yarn 1.x最常用、最稳定、文档最多、生态兼容性最好。如果你只是想让某项目里的 npm 换成 Yarn默认选这个版本即可。Yarn Berry即 Yarn 2.x / 3.x / 4.x引入了 PlugnPlayPnP机制、零安装、约束Constraints等新能力。很先进但和老项目、老 CI 链路的兼容性需要额外花心思。作为安装的第一站我的建议是先接触 Yarn Classic把基本工作流跑通再决定要不要上 Berry 这种新东西。别一上来就整最新版最新并不代表最合适。2. 安装前必须确认的电脑现状Node.js 版本和终端基本功很多人卡在安装 Yarn 的第一道坎不是安装命令敲错了而是压根没检查自己的电脑处于什么状态。Yarn 本质是一个基于 Node.js 运行的工具所以前置条件只有一条你的电脑上必须有一个可用的 Node.js 环境。2.1 如何确认 Node.js 是否就绪打开终端macOS 用户用 TerminalWindows 用户用 PowerShell 或 CMD也可以直接装一个 Windows Terminal 用输入node -v如果回车之后输出了类似v18.20.4、v20.11.1这样的版本号说明 Node.js 已经就绪。如果提示command not found或者node 不是内部或外部命令说明 Node.js 还没有安装或者没有配置环境变量。这种情况先去 Node.js 官网下载 LTS 版本安装包一路默认装完。装完记得重新开一个终端窗口再验证一次因为不少环境变量是在新窗口才会生效的。2.2 能装 Yarn 的 Node.js 版本有没有讲究Yarn Classic1.x对 Node.js 的要求很宽松当时从 Node 4 到最新的版本都支持得不错。但如果你准备用 Corepack 方式安装或者升级到 Yarn Berry则需要 Node.js 16.10 以上原因后面讲 Corepack 的时候会展开。Node.js 官网的 LTS 版本长期维护稳定性和兼容性都经过时间检验安装 Yarn 时不用刻意追求最新大版本LTS 反而是最稳妥的选择——这一点适用于绝大多数工具链。2.3 终端基础知识三种打开方式如果对终端不太熟这里给你一个最低配的操作地图Windows按Win X选择终端或Windows PowerShell。macOS打开启动台搜索终端。Linux一般用快捷键Ctrl Alt T。需要记住的是在哪个目录下执行安装命令Yarn 就装到哪个环境里。全局安装类的命令带-g参数的 npm 命令和当前工作目录无关全局生效而后续针对某个项目的 Yarn 命令则需要先cd进项目目录再执行。提示安装完成后如果提示无法确认 yarn 是否成功第一件事永远是重新打开终端窗口不要在当前窗口反复尝试yarn -v。这是新手最容易踩的坑百分之百的安装失败案例里起码有一半是这个原因。3. npm 全局安装最快见效的路径但要小心 Node 版本陷阱最直接、覆盖人群最广的安装方式是通过 npm 来安装 Yarn。前提条件是你已经有了 npm——装完 Node.js 后自带 npm所以这一步不需要额外装任何东西。3.1 执行命令打开终端直接执行npm install -g yarn其中-g表示全局安装意味着 Yarn 会被安装到系统级目录在任何路径下都能直接用yarn命令。安装过程中终端会滚动一堆进度信息等到提示added 1 package之类的信息后检查一下版本yarn -v能输出1.22.x之类的版本号就说明装好了。3.2 这种方式的本质逻辑与限制用 npm 装 Yarn本质上就是用包管理器去装另一个包管理器。这种方式在 Python 世界里也有对应的场景比如用pip install安装其他工具链。它最大的优点是无脑、兼容性好、不需要额外权限设置大部分情况缺点是 npm 本身的安装速度和解析逻辑对 Yarn 的安装体验有一定影响不过只装一次影响不大。另外一个潜在的问题是 Node 版本过旧。如果电脑上 Node.js 还是 12.x 或更老的版本执行这条命令虽然大概率也能装上但可能只能装到旧版的 Yarn 1.x后续如果需要 Yarn Berry 等新功能还得重新来一遍。3.3 为什么我不太推荐用官网安装包很多人搜索 Yarn 安装会找到官方推荐的安装包方式也就是从官网下载.msi安装文件双击、下一步、完成。这种方式的劣势很明显安装包版本的更新需要手动重新下载无法通过命令行一键升级。安装包方式有时会在 Windows 上产生路径兼容问题需要额外配置 PATH 环境变量。对于一个前端工程化工具命令行管理才符合后续折腾的思路。但不排除一种合理情况公司电脑没有 npm 外网权限或者环境要求非常严格只用安装包方式可控性更强。这种情况另当别论。3.4 新老版本切换的思路yarn 和 yarnpkg 两个命令有一个细节很多人都没注意用 npm 全局安装的 Yarn同时会生成yarn和yarnpkg两个命令它们的内容完全一样。为什么会有两个这是为了兼容早期某些项目的构建脚本里固定调用yarnpkg而保留的。实际日常使用中打yarn就行。如果后续遇到yarn命令莫名失效但yarnpkg还能用的情况不要以为是 Yarn 坏了通常是 PATH 环境变量出了问题把yarnpkg的路径证据保留下来再去排查环境变量即可。4. Corepack 方式Node 官方内置适合想长期省心的用户如果你正处于 Node.js 16.10 以上版本恭喜你其实你的电脑里已经自带了 Yarn 的管理器用不着 npm 去额外装。这个东西叫 Corepack它是 Node.js 官方推出的工具专门负责管理各种包管理器包括 Yarn 和 pnpm的版本。4.1 Corepack 和 npm 安装的本质区别npm 全局安装是把 Yarn 当作一个普通软件包塞进全局目录。Corepack 的思路则完全不同——Corepack 像一个门卫你让它放行 Yarn 某个版本它就把对应版本下载下来放到自己的缓存里然后对外提供yarn命令。两者的核心差别在于npm 全局安装的是某个具体版本的 Yarn升级 Yarn 需要重新执行 npm 命令。Corepack 管理的是多种版本 Yarn 的切换能力项目目录里声明用哪个版本就自动用哪个版本。对多项目并行开发的开发者来说Corepack 的价值非常明显。项目 A 用 Yarn 1.22项目 B 用 Yarn 4.0Corepack 能自动识别并切换。4.2 操作命令与验证前提确认 Node.js 版本在 16.10 及以上。执行corepack enable这条命令的作用是激活 Corepack 对 yarn 命令的接管。然后立即检查yarn -v理论上此时会输出一个 Yarn 版本号。如果在执行corepack enable之前电脑上已经存在另一个 Yarn 版本Corepack 默认不覆盖已有的命令需要先手动移除旧版 Yarn 或处理冲突。如果执行yarn -v提示找不到命令可以手动让 Corepack 准备一个确定版本corepack prepare yarn1.22.22 --activateprepare命令会下载指定版本的 Yarn--activate参数表示激活该版本。执行完再验证一次yarn -v输出1.22.22就说明一切正常。4.3 包管理器配置文件 packageManager 字段这是 Corepack 非常好用的一个功能。在项目的package.json里添加一个字段{ packageManager: yarn1.22.22 }当开发者使用 Corepack 环境执行yarn命令时Corepack 会读取packageManager字段自动切换到匹配的 Yarn 版本。这一点对团队协作特别友好再也不会出现我本地是 Yarn 1他本地是 Yarn 3俩人装出来的依赖行为不一样的情况。注意如果项目里的packageManager字段指定的版本 Corepack 没有缓存第一次执行yarn命令时会自动下载对应版本耗时视网络而定通常在几秒到几十秒之间第二次之后就秒开了。4.4 Corepack 与 npm 全局安装的冲突处理如果之前已经用 npm 装过 Yarn再执行corepack enable时终端通常会警告发现已有 yarn 命令或者直接不做覆盖。此时最稳妥的处理方式是把 npm 全局版本卸载掉npm uninstall -g yarn然后在项目目录里再执行corepack enable重新验证版本。干净环境永远比两个版本打架的环境好治理。5. 安装完成后的必要体检版本、路径和跑通首个项目装好 Yarn 只是万里长征第一步真正的考验是你能不能在一个真实项目里用它顺畅地安装依赖。这一节带你把体检流程过一遍每个环节都有明确的意义。5.1 版本验证的三个信息不要只满足于yarn -v输出一串数字顺手做这三个检查yarn -v which yarn # Windows 上使用: where yarn yarn --versionwhich或where能告诉你 yarn 这个命令实际存放在哪个路径。如果出现多个路径比如同时存在用户目录和全局目录下的 yarn说明你有多个 Yarn 环境这时候最好主动清理掉多余的那个否则后续很容易产生明明升级了但命令还是旧版的困惑。5.2 初始化新项目创建 package.json在任意空目录里执行mkdir my-first-yarn-project cd my-first-yarn-project yarn init -y-y参数让 Yarn 跳过交互式问答直接生成一个默认配置的package.json。生成后你可以在里面手动添加依赖也可以直接通过命令方式安装依赖。5.3 安装依赖与生成 yarn.lock假设我们需要安装一个前端工具类库还是后端框架随便选一个比如lodash一个很好用的 JavaScript 工具库yarn add lodash观察终端的输出过程你会发现 Yarn 的输出里有几个明显特征有一个进度条显示正在解析依赖关系有一个[1/4]、[2/4]这类步骤编号表示解析、抓取、链接、构建等不同阶段安装完成后出现Done in 1.23s之类的耗时统计。同时当前目录会生成yarn.lock文件这是 Yarn 的锁文件。它的作用是精确锁定每个依赖包的版本号和校验值后续任何人在任何时间执行yarn install都会严格按照这个文件下载依赖。5.4 区分 add 和 install这两个命令别搞混新手最容易混的是yarn install和yarn add的用法yarn install/yarn根据已经有package.json和yarn.lock的项目安装所有依赖。yarn add 包名安装指定包并自动写入package.json的 dependencies。刚拿到一个别人写的项目时你要做的是yarn install而你自己想在项目里新增一个依赖时才用yarn add 包名。用反了会出现项目依赖没装完但往 package.json 里乱写了东西的情况清理起来麻烦。5.5 跑脚本yarn run 的便利性package.json里的scripts字段定义了一组快捷命令{ scripts: { dev: vite, build: vite build } }用 Yarn 执行这些脚本有两种等价写法yarn run dev yarn devyarn dev是yarn run dev的简写实测两种写法完全一致。相比 npm 的npm run devYarn 少打一个run虽然看起来是小事但日积月累确实更顺手。6. 安装过程中的坑与排查链路从卡死到版本冲突逐个击破写这一节的初衷其实有点无奈。网络上 Yarn 中文教程不少但真正讲透排错的很少。我自己在实际安装和给团队配环境过程中碰到过各种千奇百怪的问题这里把高频问题按排查链路铺开写希望帮你在十分钟内定位问题。6.1 安装后yarn命令不存在PATH 环境变量问题现象安装过程全程没有报错但敲yarn -v提示找不到命令。排查链路确认安装命令是在哪个终端窗口执行的如果是新打开的窗口先关掉重开一个。查npm prefix -g这个命令输出 npm 全局安装目录的路径。检查该路径是否在你的系统 PATH 里。Windows 上打开系统环境变量设置查看 Path 里有没有这个路径macOS/Linux 上执行echo $PATH查看。如果就是缺少路径手动添加进去然后重新打开终端。6.2 安装时一直停在某个阶段网络与缓存问题现象执行yarn add时进度条长时间不动或者报出ETIMEDOUT、ENOTFOUND之类的网络错误。排查链路确认网络能正常访问 npm 官方源curl https://registry.npmjs.org。国内网络环境经常访问慢可以把 Yarn 的镜像源换为国内镜像yarn config set registry https://registry.npmmirror.com如果之前安装了一半中断Yarn 的缓存里可能有残留建议先清理再重装yarn cache clean重新执行安装命令观察是否顺畅。6.3 版本冲突电脑上有多个 Yarn现象yarn -v输出的版本号和项目里想要的不一致。排查链路执行which yarnWindows 为where yarn看是否有多个路径。对比yarn global dir和npm prefix -g的输出看全局安装路径是否有差异。如果同时存在 npm 全局安装的 Yarn 和 Corepack 管理的 Yarn建议二选一彻底移除其中一个。移除 npm 全局版npm uninstall -g yarn移除 Corepack 接管corepack disable决定留下哪种方式后重新验证版本。6.4 安装 Yarn 到项目目录而非全局目录这是一个非常迷惑人的操作。有些教程会让你先cd进某个项目目录然后执行不带-g的安装命令npm install yarn这样装出来的 Yarn 只在当前项目的node_modules/.bin/下有效——在当前项目里能用yarn出了这个项目就失效。如果你发现某个项目里yarn命令正常但换个目录就提示找不到基本就是这个原因。全局安装才是通用做法项目内安装属于特殊场景——比如某个 CI 流水线需要锁定 Yarn 版本时才会考虑。6.5 权限问题EACCES 错误在 macOS/Linux 上用 npm 全局安装时偶尔会碰到Error: EACCES: permission denied, access /usr/local/lib/node_modules这表示 npm 没有权限写入全局目录。解决的推荐思路不是暴力加sudo而是规范化 Node.js 环境的权限配置——把 npm 全局目录改到用户目录下。实际上新版 Node.js 的默认全局目录已经设置在用户目录下遇到这个错误大概率是系统里残留着古老版配置。建议重新执行 Node.js 的安装引导或者手动调整 npm 的 prefix。6.6 安装速度极慢但没报错现象不报错但yarn install动辄好几分钟。排查思路检查yarn config get registry当前用的源如果还是官方源考虑切镜像。如果电脑上安装了代理工具需要检查代理配置对终端是否生效不要让 Yarn 的流量绕到代理上去了。观察 CPU 占用和磁盘 I/O有可能会被后台杀毒软件拖慢文件写入速度这个在 Windows 上尤其常见。7. 安装完之后该给自己的环境做哪些当天见效的配置装好只是起点用得好才是目的。这里分享几个装完 Yarn 之后可以立刻做的小配置能省下不少事。7.1 配置镜像源和缓存目录如果是国内网络环境最值得做的第一件事yarn config set registry https://registry.npmmirror.com yarn config set cache-folder ~/.yarn-cache第一行切换镜像源第二行把 Yarn 的缓存目录放到用户目录下避免项目目录内的 node_modules 和缓存杂物混在一起。Windows 用户注意路径写法~在 PowerShell 中不总是直接可用可以用完整路径替代yarn config set cache-folder D:\yarn-cache7.2 初始化全局配置yarn init 默认字段如果你希望以后每次yarn init生成的 package.json 都预填一些固定字段比如作者名、许可证可以编辑~/.yarnrc文件init-author-name Your Name init-license MIT这样每次初始化项目就不用反复填写这些无聊信息了。7.3 打开 ignore-optional 选项按需有的项目安装时会把可选的平台相关依赖一并装进来在部分 Windows 开发机上会碰到下载个别二进制包极慢的情况。可以临时关闭可选依赖yarn config set ignore-optional true但要注意这个设置会漏掉一些真实有用的可选依赖包不建议全局永久开启只在碰到具体问题时临时启用。7.4 让 Yarn 和 VS Code 编辑器配合得更顺畅如果在编辑器比如 VS Code的终端里执行yarn命令失败但独立终端里又能正常执行通常是因为编辑器没有继承终端环境变量。解决方法是重启编辑器或者在编辑器的设置里指定终端环境变量路径。注意以上配置修改后建议执行yarn config list查看当前全部配置确认没有意外的全局覆盖项。配置排查是后续一切疑难杂症的定海神针。8. 最后补一刀给新手的几条实在建议如果回归到下载安装 Yarn这个话题本身我个人在实际操作中的体会有几点想特别强调。第一安装 Yarn 本身不是目的项目跑起来才是。不要花太多时间纠结用 npm 装还是 Corepack 装先以最顺手的路径装好开一个项目跑通yarn install和yarn dev或yarn start比研究十篇最佳实践都有用。第二Node.js 版本要定期看一眼。很多人换了新电脑装完 Yarn老项目里发现一堆兼容问题最后定位出来是 Node 版本太老或者太新引来的。这不是 Yarn 的问题但 Yarn 作为工具链链路里的一环很多时候会成为背锅侠。第三如果工作中要跟团队协作务必把yarn.lock提交到代码仓库。它就像是快递包裹里的清单人和人之间、机器和机器之间的依赖安装结果是否一致全靠它。忽略 lock 文件的做法等于给团队埋了一颗定时炸弹。第四善用 Yarn 缓存。在 Yarn 里yarn cache list可以查看当前缓存了哪些包yarn cache clean可以清理。理论上 Yarn 的缓存会让不同项目的相同依赖安装速度大幅提升前提是不要频繁清理它。有些工具会在 CI 时一键清缓存结果导致每次构建都要重新下载一大堆包白白浪费时间。如果从这篇文章里只带走一个结论那就是Yarn 不难装真正难的是理解你为什么要装它以及装完之后怎么让它为你的项目流程服务。毕竟工具这东西只有在用得顺手、踩得动坑的时候才算是真正属于你的能力。