★ FEATURED ARTICLE 先把结论放在这里如果你现在在网上搜“怎么下载安装yarn”大概率会翻到两类东西——一类是教你怎么装JavaScript的包管理器Yarn另一类则是搜到了那个专门找电影台词截图的同名网站。后者虽然也有点意思但不是咱们要聊的东西。这篇文章只讲一件事把Yarn包管理器从头到尾装好装完还能流畅地用起来不踩坑、不返工。顺便说一句Yarn这名字起得确实容易让人误会。它在英文里的本意是“纱线、毛线”所以你在搜索引擎里混着搜甚至能搜出一堆织毛衣的教程。做前端这几年我前前后后在Windows、macOS、Linux上都装过Yarn也被PATH、镜像源、Corepack这些乱七八糟的事情折腾过。这次就把这些经历整理成一篇可以直接照着做的实操笔记覆盖常见安装方式、环境变量配置、镜像源提速、常用命令以及问题排查适合从没用过Yarn的新手也适合被环境问题卡住想快速脱困的老手。1. 安装之前先摸清这些底别装了个寂寞1.1 Yarn到底是什么为什么放着npm不用非要用它Yarn 是 Facebook现在叫 Meta团队在 2016 年开源的一个JavaScript包管理器本质上和 npm 做的是同一件事帮你下载项目依赖、管理版本、执行脚本。当初它出现的直接原因是 npm 在早期版本里实在是太慢了——安装依赖是串行的一个包一个包排队下载项目中依赖一多等得人直想摔电脑。Yarn 一出来就做了几件核心优化让依赖安装的速度和稳定性都有了质变并行下载多个依赖同时拉取而不是排队等待整体耗时大幅缩短。离线缓存机制所有下载过的包都会保存在本地缓存目录中下次安装相同版本时直接读缓存秒级完成不用重新去服务器拉。yarn.lock 锁文件帮你把每个依赖的精确版本固定下来团队协作时大家装出来的依赖树完全一致消灭了“我机器上跑得好好的你这儿怎么一跑就崩”这类玄学问题。虽然如今 npm 也补上了锁文件package-lock.json和缓存机制速度也提升了不少但 Yarn 依然是很多公司的标准选择尤其在前端工程化、Monorepo 这类场景中Yarn 的 workspace 能力成熟稳定。装一个不亏。1.2 安装前的硬性环境检查清单Yarn 本身不是一门语言它运行在 Node.js 之上。所以安装 Yarn 前你的机器里必须已经有 Node.js这是硬前提。第一步先检查 Node.js 是否已安装。打开终端Windows 用 PowerShell 或 CMDmacOS 用终端 App执行node -v如果有输出类似v18.16.0的版本号说明 Node 已就绪如果提示“node 不是内部或外部命令”请先到 Node.js 官网下载 LTS 版本完成安装再回来继续。第二步顺便看一眼 npm 是否可用npm -v为什么要看 npm因为下面我们要讲到的第一种安装方式就是通过 npm 来安装 Yarn没有 npm 就装不了。当然Node.js 从 16.10 版本开始内置了 Corepack这也是一条官方推荐的安装路径稍后我会单独讲。最后还要确认一下 Node.js 的版本满足 Yarn 的要求。如果你打算用 Yarn 1.x经典版Node 12 就够用如果要用 Yarn 4.xBerry 版建议 Node 18 或更高版本。现在新装的 Node 基本都是 LTS 版本不太会出现版本过低的问题但检查一下不亏。另外不同操作系统对应的推荐安装方式不完全一样。我整理了一张对照表你可以根据你的系统快速定位系统推荐安装方式次选方式备注WindowsCorepack 或 npm 全局安装Chocolatey / Scoop注意 PATH 配置Windows 最容易踩坑macOSHomebrew 安装Corepack / npm 全局安装Homebrew 方式会同时处理好 PATHLinuxCorepack 或 npm 全局安装apt / dnf 安装系统源里的版本可能偏旧不推荐作为首选2. 三种主流安装方式怎么选都不亏2.1 方式一npm 全局安装最通用新手首选这是最简单直接的方式不需要额外安装任何工具只要你的 Node.js 环境正常一条命令就能搞定。打开终端执行npm install -g yarn-g表示全局安装装完后 Yarn 的命令会被放到 npm 的全局 bin 目录下。安装完成后验证一下yarn -v正常情况下会输出一个版本号比如1.22.22。如果你装的是 Yarn 1.x那到此为止就是安装成功了。如果你希望使用最新的 Yarn 4.x那还要额外配置 Corepack 或者通过 npm 安装 yarnlatest这个稍后讲。这里有两个非常常见的坑需要提前说一下。第一在 macOS 上执行npm install -g yarn时你可能会遇到EACCES: permission denied之类的权限错误。这是因为全局目录默认需要更高权限。很多人会顺手加个sudosudo npm install -g yarn加了 sudo 一般能装上但我不推荐你长期这么干。它本质上是让你用管理员权限去修改 npm 的全局目录轻则以后每次全局装包都要 sudo重则把文件权限搞得乱七八糟。更好的做法是修改 npm 的全局目录到你自己的用户目录下。执行npm config set prefix ~/.npm-global然后编辑~/.bashrc或~/.zshrc把下面这行加进去export PATH$HOME/.npm-global/bin:$PATH刷新配置后重新执行yarn -v权限问题就彻底解决了。第二Windows 用户安装完 Yarn 后如果是新开的终端窗口通常没啥问题但如果你是在安装完成前就已经打开了终端那这个终端窗口里可能读不到新加的 PATH依然提示“yarn 不是内部或外部命令”。这不是没装上而是 PATH 没刷新。最简单的处理办法关掉所有终端窗口重新打开一个再执行yarn -v。2.2 方式二Corepack官方推荐的现代路线Corepack 是当年 Node.js 团队为了规范前端包管理器的版本管理而引入的工具从 Node.js 16.10 开始随 Node 一同发布不需要额外安装。它的巧妙之处在于它本身是一个“版本管理器”可以在一个项目里灵活指定 Yarn 的版本不会和其他项目相互污染。如果你要启用 Yarn先开启 Corepackcorepack enable然后准备你想要的 Yarn 版本。以最新的稳定版为例corepack prepare yarnstable --activate这条命令会去下载指定的 Yarn 版本并把它激活为当前环境默认版本。验证一下yarn -v这时输出的版本号大概率是4.x.x也就是 Yarn Berry。这条路线的优势很明显不用手动折腾 PATH也不会因为 npm 全局目录权限问题卡壳。另外在一个新项目里你可以在package.json的根目录写明packageManager字段之后 Corepack 会自动根据这个字段切换 Yarn 版本。它很适合进阶用户使用。需要注意如果你的 Node.js 版本低于 16.10Corepack 是不自带的你需要通过 npm 单独安装npm install -g corepack2.3 方式三系统包管理器安装macOS / Linux 友好除了 npm 和 Corepack你还可以直接使用系统的包管理器来安装 Yarn。macOS 上用 Homebrew 安装最省心brew install yarnHomebrew 会自动处理好 PATH装完即可直接使用。这种方式非常适合 Mac 用户个人体验下来也很干净。Windows 上如果你平时习惯用 Chocolatey 或 Scoop也可以试试choco install yarn或者scoop install yarnLinux 上不同的发行版对应的命令不一样。以 Ubuntu / Debian 为例apt install yarn但我个人不太推荐 Linux 上优先用系统源安装因为系统软件源里的 Yarn 版本往往偏旧而且包的更新节奏跟不上官方装完之容易遇到“老版本不支持新项目”的问题。Linux 上我最推荐的方式还是 Corepack 或 npm 全局安装。2.4 三种方式怎么选直接给结论新手、赶时间、想最快用上npm 全局安装一条命令解决。愿意花 5 分钟折腾一次、希望长期省心Corepack 路线版本管理清晰项目间隔离性好。macOS 用户Homebrew 也完全没问题最省事npm 和 Corepack 同样适合。Linux 用户优先 Corepack 或 npm 全局安装尽量不用系统源。这三种方式之间并不是互斥的它们之间也不存在“卸载一个才能装另一个”的约束。如果你现在环境里有旧版 Yarn 想升级直接按照自己的场景执行对应命令即可。3. 环境配置这一步没弄好装完也白装3.1 PATH 和全局目录为什么命令就是找不到安装完成只是第一步环境配置才是真正的分水岭。很多新手安装明明成功了一执行yarn却提示找不到命令十有八九是 PATH 没配对。PATH 是什么你可以简单理解成一个“可执行命令的查找名单”当你输入yarn时系统会按照 PATH 中记录的目录顺序挨个去找有没有一个叫 yarn 的可执行文件。如果文件不在这些目录里系统就直接告诉你“找不到”。我们先来定位一下 Yarn 被安装到了哪里。在终端执行where yarnWindows 下会输出类似这样的路径C:\Users\你的用户名\AppData\Roaming\npm\yarn C:\Users\你的用户名\AppData\Roaming\npm\yarn.cmd如果能看到输出说明 Yarn 文件确实存在那问题大概率就出在 PATH 没有包含上面的目录。解决办法是打开“系统属性 - 环境变量”在“用户变量”里找到Path把上面输出中的C:\Users\你的用户名\AppData\Roaming\npm加进去。加完后重新打开终端再执行yarn -v验证。macOS 和 Linux 下用which yarn或whereis yarn如果输出路径存在一般不太会出现 PATH 缺失的问题——除非你用的是某些非交互式登录 shell配置文件没加载全。这时候检查一下~/.bashrc、~/.zshrc把 Yarn 的 bin 目录手动添加进PATH即可。还有一类情况需要留意有时候你执行yarn -v正常但执行yarn global bin时输出的路径和你当前的 PATH 对不上——这是因为全局 bin 目录和当前 PATH 中生效的目录并不一致。这时候建议你顺手把 Yarn 的 global bin 目录也加到 PATH 里避免后面yarn global add安装的命令找不到。执行yarn global bin把输出的路径添加进上面的环境变量列表即可。3.2 镜像源配置让你的依赖下载速度起飞Yarn 默认使用的依赖源是官方源在国内访问时下载速度一言难尽——装个小包能等上半天大型项目光装依赖就能把人逼疯。好在国内有靠谱的镜像源可以切换速度会快上几个数量级。先看看你当前使用的源地址yarn config get registry如果输出的不是https://registry.yarnpkg.com说明你可能之前已经配置过如果是默认源建议切换成镜像源。切换命令如下yarn config set registry https://registry.npmmirror.com --global这里加--global表示全局生效对所有项目有效。如果你想只在某个项目里使用这个源去掉--global即可这样不会影响其他项目。执行完再验证一下yarn config get registry看到输出了https://registry.npmmirror.com说明配置成功。之后再执行yarn install你就能感受到明显的速度差异了。有一点需要提醒团队协作时不要让某个成员单独修改镜像源不加说明。虽然镜像源只会影响下载速度不会影响依赖内容但出现问题排错时环境的统一性能少浪费很多时间。如果是团队项目优先把 registry 配置写进项目级的.yarnrc.yml文件里这样大家拉下来代码后自动使用相同的源。3.3 验证安装是否真正可用的三个关键命令环境配置完成后建议按顺序执行以下三个命令做最终验证确保不是“假成功”yarn -v node -v yarn config get registry正常输出的预期结果大致是yarn -v输出一个版本号看到 1.x 或 4.x 都是正常的node -v输出 Node 版本号确保环境与 Yarn 的运行时兼容最后一步能看到刚才配置的镜像源地址。这三个都通过你的 Yarn 就真正达到了随时可用的状态。4. 从零到一Yarn 的常用命令与项目落地技巧4.1 初始化一个项目yarn init安装配置完成接下来要做的事就是真正用起来。先从初始化一个项目开始。找个空目录进入目录后执行yarn init -y-y参数表示所有交互式提问都用默认值快速生成一个package.json。如果你希望手动填写项目名称、版本、描述等信息直接执行yarn init然后根据提示逐项回答即可。生成的package.json大概长这样{ name: my-demo, version: 1.0.0, main: index.js, license: MIT }这个文件就是整个项目的“清单”后面所有依赖都会记录在它里面。4.2 安装与卸载依赖yarn add 与 yarn remove在项目里安装一个新依赖最简单的方式是yarn add lodash这条命令会做三件事下载 lodash 包、把它写入package.json的dependencies字段、更新yarn.lock锁文件。以后别人拿到这个项目直接执行yarn install就能装出和你完全一致的依赖环境。如果你是开发阶段才用的工具类依赖比如测试框架、构建工具那应该安装到devDependencies加一个-D参数即可yarn add -D jest卸载依赖就简单了yarn remove lodash它会把 lodash 从package.json和yarn.lock中一并清理掉。还有一个我经常用到的命令是yarn install和它的进阶版yarn install --frozen-lockfile。前者会按照锁文件安装依赖后者会强制严格按锁文件安装如果发现yarn.lock和package.json不匹配就报错而不是自动修正——这个在 CI/CD 流水线里非常实用能确保测试环境与本地环境完全一致。4.3 排查依赖问题yarn why 与 yarn outdated日常开发里还有两个排查看家的命令值得记下来。当你发现项目里某依赖出现了一个兜圈子的版本冲突又不知道是谁引进来的时候执行yarn why some-package输出会列出这个版本的依赖依赖了它、为什么安装了这个版本。在大型工程里这个命令能省下大量排查时间。想看当前所有依赖是否有新版本执行yarn outdated它会列出一个表格告诉你哪些包有更新当前版本是多少最新版是多少以及是 major、minor 还是 patch 级别的更新。手动升级时可以先用这个命令做一次评估再决定要不要yarn upgrade。4.4 离线缓存解决“换台电脑就装不动”的尴尬Yarn 从 1.x 时代开始就自带了一个强大的缓存机制所有下载过的依赖包都会存一份在本地。缓存目录可以通过下面命令查yarn cache dir默认情况下缓存是自动管理的。如果你需要离线安装依赖已经用 Yarn 装过一次的项目然后再在无网络的环境中去执行yarn install --offlineYarn 就会优先从本地缓存读取而不是去请求网络。实测下来配合锁文件这种方式在内网开发环境和 CI 上表现相当稳定。必要时候你还可以手动指定缓存目录部署到内网服务器实现团队级的离线条线。5. 常见问题与排查实录都是踩过的真坑5.1 高频问题速查表结合我自己的经历和身边同事踩过的坑把高频问题整理成一张速查表按图索骥可以省很多时间现象可能原因解决办法提示“yarn 不是内部或外部命令”PATH 没配或没刷新用where yarn或whereis yarn定位把对应 bin 目录加入 PATH关掉旧终端重开macOS 装包提示权限不足 EACCESnpm 全局目录权限问题不要直接 sudo改用npm config set prefix ~/.npm-global并配置 PATHPowerShell 不允许运行脚本报 script not signedWindows 执行策略限制以管理员身份运行 PowerShell执行Set-ExecutionPolicy RemoteSigned确认 Y安装依赖时提示证书过期或 SSL 错误默认源网络不稳切换到镜像源yarn config set registry https://registry.npmmirror.com --global报错Command yarn not found但 yarn 明明装了当前终端环境没加载 PATH重启终端如果还不行检查 shell 配置文件是否有 export 那句corepack enable提示找不到命令Node 版本过旧低于 16.10升级 Node或npm install -g corepackyarn install卡住不动默认源太慢切换镜像源检查网络代理是否污染了下载流量项目里执行 yarn 用的是 1.x但你项目要 4.xCorepack 未启用或版本没切在项目package.json写packageManager: yarn4.x.x然后重新执行corepack prepare5.2 典型场景一Windows 下装完 yarn但报错“不是内部或外部命令”这个现象真的是高频中的高频。有位同事小白阶段在 Windows 上装完 Yarn执行yarn -v直接看到“yarn 不是内部或外部命令”一度以为卸载重装能解决。我告诉他别急先执行where yarn结果输出了一个AppData\Roaming\npm\yarn路径——文件就在那儿说明装成功了。那问题就只剩 PATH 没包含这个目录。按下面的步骤操作一遍即可右键“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“用户变量”中找到Path双击编辑。点击“新建”粘贴C:\Users\你的用户名\AppData\Roaming\npm。一路“确定”保存然后关掉当前所有终端窗口重新打开一个 PowerShell。再执行yarn -v正常输出版本号。5.3 典型场景二Yarn 1.x 与 Corepack 的“版本冲突”还有一个不少朋友会遇到的场景你已经通过 npm 安装了 Yarn 1.22后来为了新项目用了 Corepack 启用 Yarn 4.x但执行yarn -v时发现还是 1.22。怎么回事其实就是 PATH 的查找顺序问题。npm 装的 Yarn 在AppData\Roaming\npm目录下而 Corepack 管理的 Yarn 在 Node 安装目录附近。系统在 PATH 中先匹配到了 npm 装的那个就停下来了不再往后找。解决办法很直接把 npm 全局目录里的那个 Yarn 卸载掉或者调整 Corepack 相关目录优先于 npm 目录。如果确定新项目全部统一走 Corepack 版本管理最省心的做法是卸载掉全局 npm 装的 yarnnpm uninstall -g yarn然后再执行corepack enable和corepack prepare yarnstable --activate这样就能确保yarn -v走的是 Corepack 管理的版本了。5.4 关于“Yarn 网站搜索电影台词”那个同名神器顺带提一嘴最后辟个谣。你搜“yarn”的时候看到的那个搜索电影台词截图网站和咱们今天装包管理器 Yarn 完全不是一码事。前者是一个英文电影台词搜索网站数据来自一堆影视剧的字幕适合找表情包、找台词来源后者是注入工程依赖的工具。很多新手搜教程时被这个名字搞糊涂甚至以为装错了软件。下次如果再把人搞混分不清就说“我在搞前端那个包管理器 yarn”基本就不会错。6. 最后分享我这几年的实操心得随手写几点个人体会不指望面面俱到但都是实打实的经验。第一如果你只是偶尔用 Yarn 跑跑个人项目就用 npm 全局安装省事。如果你是要在公司长期搞前端工程强烈建议把 Corepack 用熟了——它能让你每个项目用各自的 Yarn 版本避免了“这个工程要 Yarn 1.x那个要 Yarn 4.x两个人切来切去装到底哪个”的混乱。我自己的经验是被这种版本冲突折磨过一次后就彻底倒向了 Corepack。第二别忽视缓存的好处。以前总觉得依赖不过是几秒钟下载的事直到有一次在隔离内网部署网络环境极其受限全仗着 Yarn 的离线缓存项目才顺利构建。从那以后我习惯在任意一台网络好的机器上先把大项目的依赖装两遍确保缓存预热再去离线环境操作。这个习惯救了我不止一次。第三遇到任何安装问题先别急着卸载重装。按顺序检查三件事PATH 配了没有、终端重启了没有、镜像源切了没有。我见过太多人反复卸载安装同一个软件最后发现只是第一步没做。装环境这件事90%的问题都能通过“确认路径、刷新环境、换源加速”三步解决。这篇文章到这里就写完了。如果你正好卡在 Yarn 的安装配置上希望上面这些内容能帮你少走几条弯路。如果还碰到什么没写到的怪问题欢迎评论区补充遇到过的朋友也能互相搭把手。
阅读完成 · 觉得有帮助？
