最近好几个群里都在问“怎么下载安装 yarn”这个问题看着简单实际回答起来挺费劲因为得先搞清楚三件事你是什么操作系统你电脑里的 Node.js 是什么版本以及你想要的 Yarn 是经典版1.x还是新版 Berry2.x 之后。不同组合安装命令完全不一样。这篇文章我就把环境检查、主流安装方式、各平台的细节差异、常见报错一次讲透照着操作十分钟内能跑通。Yarn 是 JavaScript 生态里非常常用的包管理器由 Facebook 在 2016 年发布解决的是当时 npm 的几个老毛病安装慢、依赖版本不确定导致“我这边没问题你一拉就崩”、缺少离线缓存机制。它用yarn.lock锁文件把依赖树固定下来又通过并行下载和全局缓存把安装速度提上去所以至今在很多前端团队里依然是主力工具。无论你是做 Vue、React 项目还是维护 Monorepo 仓库都会跟它打交道。这篇博文适合刚入门的前端新手也适合被各种报错困住、想换个装法的老手。1. 安装前先搞清楚Yarn 到底是什么为什么需要单独装1.1 从 npm 到 Yarn它解决了什么问题如果你用过 npm会发现它并不是不能用只是在特定场景下比较折磨人。最典型的就是package-lock.json在不同人手里生成的版本不一致或者一个大项目npm install要等很久。Yarn 当年的核心改进有三个一是确定性只要yarn.lock在任何机器装出来的依赖树都一样二是速度依赖被缓存到本地二次安装几乎秒开三是离线能力缓存里有就能直接装。这些特性在 2016 年那个时间点非常惊艳所以大量开源项目很快切到了 Yarn。虽然后来 npm 自己也加了 lockfile、缓存加速但 Yarn 在工程化场景下的体验尤其是新版本 Berry 的 PnPPlugnPlay模式依然有一批忠实用户。1.2 分清 Yarn 1 和 Yarn Berry安装命令完全不同这点特别重要因为现在网上的资料新旧混杂照着旧教程去装新版大概率会踩坑。Yarn 1.xClassic传统模式依赖装在node_modules用npm install -g yarn就能装命令是yarn。Yarn 2.x / 3.x / 4.xBerry默认启用 PnP 模式node_modules可以不存在依赖通过.pnp.cjs管理官方强烈建议通过 Node.js 自带的 Corepack 来安装而不是用 npm 全局装。一句话总结新项目建议直接上 Berry用 Corepack 装老项目要兼容旧的 CI 脚本可能还得用 Yarn 1。这篇博文主要讲安装但我会把这两条路线都写清楚。2. 安装前的环境准备先把 Node.js 版本检查好2.1 检查 Node.js 环境Yarn 是跑在 Node.js 之上的所以前提是你的电脑里得有 Node.js 和 npm。打开终端Windows 上建议先打开 PowerShell 或 CMD依次执行node -v npm -v如果这两个命令都正常输出版本号说明基础环境没问题。如果提示command not found那你得先去 Node.js 官网下载 LTS 版本安装这一步绕不开。我见过很多人一上来就直接npm install -g yarn结果提示npm: command not found其实就是 Node 都没装好。所以安装前先花三十秒检查环境能省掉后面一半的麻烦。2.2 Node 版本和 Yarn 版本的兼容关系不同 Yarn 版本对 Node.js 的版本要求不一样装之前心里最好有个数Yarn 版本最低 Node 要求推荐 Node 版本Yarn 1.xNode 4.014.x 以上可用但仍建议 16/18Yarn 2/3/4Node 12.016.13 或 18.x LTS通过 Corepack 安装Node 16.9 才内置建议直接用 18.x LTS我自己现在习惯用 nvmNode Version Manager来管理 Node 版本这样不同项目切 Node 版本很方便也不会因为某个项目要求旧 Node 而卡住。macOS 或 Linux 用户推荐装 nvmWindows 用户可以用 nvm-windows也可以直接用官方安装包。提示如果你电脑里的 Node 比较老比如 14 以下又想用新版 Yarn先升级 Node别硬装。3. 三种主流安装方式详解含避坑记录3.1 方式一Corepack 官方推荐最省心Corepack 是随 Node.js 一起发布的一个“包管理器管理器”从 Node 16.9 开始内置。它的作用是帮你自动管理 Yarn 和 pnpm 的版本。你不需要全局安装任何东西只需要把 Corepack 的“开关”打开然后让它准备一个 Yarn 版本激活就行。第一步启用 Corepackcorepack enable第二步激活一个具体的 Yarn 版本。想用最新稳定版corepack prepare yarnstable --activate第三步验证yarn --version我看到你项目里如果package.json里声明了packageManager字段比如packageManager: yarn3.6.1那么首次在项目目录里运行yarn install时Corepack 会自动下载并切换到对应版本的 Yarn。这个机制非常优雅团队里每个人装的 Yarn 版本都一样不会出现“我用 1.x 你用 4.x”的混乱。这里有个细节需要注意corepack enable工作时会给当前 Node 的 bin 目录生成软链接/快捷方式让yarn命令直接指向 Corepack 的 shim。如果你的 Node 是通过 nvm 装的并且开启了多个 Node 版本请确保你是在当前即将使用的那个 Node 版本下执行corepack enable否则可能遇到“开是开了但换个 Node 版本又没了”的情况。注意如果你安装 Node 时选择了“全部默认”的 Windows 安装包Corepack 可能没被加入 PATH。这时候需要回到 Node 安装目录手动把 corepack 的目录加进环境变量或者在开始菜单里重新运行 Node.js 对应的“Corepack enable”脚本。3.2 方式二npm 全局安装适合装 Yarn 1如果你就是想要经典的 Yarn 1.x那最直接的命令是npm install -g yarn这条命令会从 npm 仓库把 Yarn 1 的最新版本全局装上。装完执行yarn --version能看到1.22.x说明安装成功。这种方式的最大缺点是它把 Yarn 当作 npm 的一个普通全局包来管理。这样有两个隐患第一如果你电脑上同时有多个 Node 版本比如用 nvm 切换每个 Node 环境都要单独装一遍第二以后要升级 Yarn得靠npm install -g yarnlatest和项目的版本绑定关系比较弱。所以我现在的建议是能用 Corepack 就别用 npm 全局装。除非你的项目还在用 Yarn 1 的脚手架或者公司 CI 脚本指定要用全局 Yarn否则没必要。3.3 方式三独立安装脚本、Homebrew 等平台工具macOS 用户比较喜欢用 Homebrewbrew install yarnWindows 用户还可以用 Scoop 或 Chocolateyscoop install yarn # 或 choco install yarn这类方式本质上是把 Yarn 1 的可执行文件放到系统里操作简单但在版本单一化这件事上同样没优势。另外还有一个带点“野路子”味道的安装脚本方式Yarn 官网早期提供的curl -o- -L https://yarnpkg.com/install.sh | bash我个人强烈不建议这么干。把网上的脚本直接管道给bash执行等于让你电脑无条件信任那个远端内容一旦脚本被人篡改风险非常大。哪怕你真的很急也建议先把脚本用 curl 下载到本地打开看一眼再执行。4. 各平台差异Windows / macOS / Linux 细节大盘点4.1 Windows 上的常见坑Windows 上最容易出问题的点有三个。第一个是终端环境不一致。用 CMD、PowerShell、Git Bash 执行命令结果可能有微妙差异。比如corepack enable在某个终端下执行成功换一个终端又说找不到命令大概率是环境变量没刷新。解决办法改完环境变量或装完东西后关掉当前终端重新开一个别图省事。第二个是 PowerShell 执行策略。如果你执行yarn时遇到“因为在此系统中禁止执行脚本”之类的报错需要在管理员 PowerShell 里调整执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个操作只允许本机创建的脚本和已签名脚本运行安全性和便利性平衡得比较好。第三个是 Git Bash 的路径问题。在 Git Bash 里执行where yarnWindows 下查找命令和which yarnGit Bash 里的命令结果不一定一致。如果你发现同一条命令在两个终端里调用的 Yarn 版本不同说明 PATH 里有多个 Yarn需要把想要的那个路径排到前面。4.2 macOS 上的几个小细节macOS 上如果你用 Homebrew 装了 NodeCorepack 默认是跟着 Node 走的直接在终端输入corepack enable就行。不过如果 Node 是用官方 pkg 安装包装的装完之后终端不一定立刻识别corepack命令同样建议重启终端。还有一个经常被忽略的地方如果你用了 zsh并且配置了.zshrc注意 PATH 的覆盖顺序。我之前遇到过which yarn指向了/opt/homebrew/bin/yarn但实际项目里想用 Corepack 管理的 Yarn结果被旧版本截胡。排查办法是先执行which yarn看路径再用手动调用完整路径去确认版本。4.3 Linux / CI 环境怎么处理服务器或 Docker 容器里通常没有交互式终端也不会有 nvm 那种交互工具。最干净的做法是在 Dockerfile 里显式启用 Corepack。以 Node 18 的官方镜像为例RUN corepack enable \ corepack prepare yarnstable --activate然后在构建阶段直接用yarn install或yarn build即可。这里提醒一句很多 CI 缓存策略里会缓存.yarn目录和.pnp.cjs如果你换了 Yarn 版本记得把 CI 缓存键也更新否则容易出现“本地 OKCI 上报错”的经典问题。缓存目录清理命令是yarn cache clean不过这句要在项目目录里跑别在全局目录瞎跑有些版本的 Yarn 不支持全局范围清理也会提示错误。5. 安装完成后的验证与初始化配置5.1 三步验证你的 Yarn 是否真的能用只敲yarn --version可不够我建议按下面这套流程验证一遍yarn --version yarn config list mkdir -p /tmp/yarn-test cd /tmp/yarn-test yarn init -2说明一下各个步骤的作用。yarn --version看版本号对不对yarn config list看当前生效的配置项尤其要看registry指向哪里yarn init -2是创建一个 Yarn 2 风格的项目初始化文件新版 Yarn 用-2参数还有额外的初始化流程能看到package.json里是否自动写入了packageManager字段。如果你发现yarn init之后项目里生成了.yarnrc.yml而不是.yarnrc说明你用的确实是 Berry 版本这是正常的不用慌。新版 Yarn 的配置文件就是.yarnrc.yml旧版的.yarnrc只在 Yarn 1 里生效。5.2 初始化后要不要调整这几点配置装好 Yarn 不等于万事大吉有几个配置项我建议你根据项目情况顺手设好。第一是镜像源。如果你在国内网络环境下安装依赖很慢可以把 registry 指向镜像yarn config set registry https://registry.npmmirror.com国内有很多公司内部源但公开可用的镜像源里 npmmirror 比较常用。注意这个设置会影响当前用户所有的 Yarn 项目某些公司要求在项目目录下yarn config set registry 内网地址才能走内网两者并不冲突。第二是 Berry 的nodeLinker。默认的新版 Yarn 用 PnP 模式不会生成node_modules很多老工具链可能不认识。如果你不想引入 PnP 的调试成本可以在项目.yarnrc.yml里加nodeLinker: node-modules这样 Yarn 还是老一套node_modules路径但用的是新版引擎兼容性更好。我的经验是接入老项目时先选node-modules跑通之后再考虑切 PnP别一上来就开最高难度。第三是编辑器集成。如果用 PnPVSCode 需要安装 ZipFS 插件否则打开项目时编辑器解析依赖路径会飘红。这个不装不致命但很影响体验。6. 常见问题与排查技巧实录6.1command not found: yarn到底哪里没对这个报错出现的概率最高排查顺序基本是先确认 Node 装了没再确认 Yarn 装在哪个环境里了。按命令来看node -v npm -v如果这两个都有接着执行which yarnmacOS/Linux 用whichWindows 用where yarn。如果没有任何输出说明 Yarn 没装到当前 PATH 能覆盖的范围内。常见原因有两个一是 Corepack 没 enable二是 npm 全局 bin 目录没在 PATH 里。第二个情况 Windows 上特别常见装完 Node 后 npm 全局目录被设置成了%APPDATA%\npm如果它不在系统 PATH 里全局命令全部失效。6.2 两个 Yarn 版本打架怎么判断自己用的是哪个项目里经常出现这种情况终端里敲yarn --version显示1.22.19但项目里确实用了 Yarn 4 的配置。这大概率是你全局还有旧版 YarnCorepack 的 shim 优先级没顶上。解决方法corepack enable corepack prepare yarnstable --activate执行完再敲which yarn看看路径有没有变化。如果还是旧版把那条旧路径对应的全局包卸掉。npm 全局装的 Yarn 1 用npm uninstall -g yarnHomebrew 装的用brew uninstall yarn卸完之后重新验证版本确保终端里的yarn指向 Corepack 管理的版本。6.3 镜像源导致锁文件校验失败这是在中国网络环境下最容易踩的坑。你把 registry 指向了镜像源之后yarn.lock里的resolved字段会存成镜像地址integrity哈希字段也会对应镜像上包的 hash。当你切换网络环境或者同事用官方源拉取时校验对不上运行yarn install就会报错。处理办法先想清楚团队统一用哪个源然后把这个源写进.yarnrc.yml或者.npmrc里并提交到仓库大家保持一致。已经出问题时重新让 Yarn 按新配置生成锁文件的分支更新即可。不建议直接删yarn.lock除非你确定依赖可以全部重装。6.4 PowerShell 禁止执行脚本的处理Windows 用户执行yarn命令偶尔会遇到下面这类红色提示因为在此系统上禁止运行脚本。最省事的解法是在管理员 PowerShell 里执行我前面提到的Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重开终端再试。这个命令的原理是让 PowerShell 允许运行本地创建的脚本以及经过签名的远程脚本正好覆盖 Corepack 生成的 shim 和各类全局命令的启动脚本。对于个人开发机来说这样的策略等级是合理的。公司管理机如果组策略锁死了这一项那就老老实实用 CMD 或者其他已经被允许的终端。6.5 项目里显示用的是 Yarn 1但没装全局包怎么定位如果你用 Corepack 方式项目切换 Yarn 版本默认是“按需激活”。你第一次在项目目录里跑yarn时Corepack 会根据package.json里的packageManager字段下载对应版本。如果项目里没有这个字段就按系统里激活的默认版本走。所以想让整个团队统一版本请务必在项目里提交packageManager字段。手动给当前项目设定版本yarn set version stable或者指定某个 4.x 版本yarn set version 4.5.0执行后会自动生成.yarnrc.yml并在里面标记版本来源同时更新packageManager字段。这一步做完项目里的 Yarn 版本才算是被“锁定”了。7. 升级与卸载装好了之后还要会管7.1 升级 Yarn 的正确姿势不同安装方式的升级命令差异很大别混着用Corepack 方式corepack prepare yarnstable --activate或者项目里用yarn set version stable把当前项目升到最新稳定版。npm 全局方式npm install -g yarnlatest。Homebrew 方式brew upgrade yarn。升级之后一定先跑一下yarn --version确认版本号符合预期。如果旧项目升级大版本比如从 1.x 跳到 4.x强烈建议先在一个分支上跑yarn install观察yarn.lock的更新范围和node_modules的变化不要直接在主干上动。Yarn 4 从 3.x 升级过来一般还算平滑但如果你用的是 Yarn 1 的老项目直接切到 4 可能会遇到不少 plugins 缺失的问题比如workspace-tools、version这些核心插件在新版里默认不在。迁移计划要留足时间。7.2 卸载时注意别把团队配置文件删了如果你只是想“不用 Yarn 了”全局卸载很简单npm uninstall -g yarn但项目里的痕迹不会自动消失。如果项目要用回 npm你需要在项目目录里把.yarnrc.yml、.yarn/目录以及package.json里的packageManager字段都处理掉否则队友拉代码后还是会被 Corepack 引导用 Yarn。反过来如果还有队友在用 Yarn你只是自己换工具那就别动项目里的任何 Yarn 相关文件。卸载全局 Yarn 只影响你自己电脑上的命令可用性不影响仓库里提交的文件。我个人在实际操作中的体会是Yarn 的安装问题九成以上不是“装不上”而是“装的位置和你以为的不一样”。环境变量、PATH 顺序、Corepack 开关这三个点是排查的主力方向。如果你按我上面说的先检查 Node 版本、再决定用 Corepack 还是 npm 全局、最后用which yarn验证路径整个流程会顺很多。最后再分享一个小技巧团队协作时尽量让 Yarn 版本由项目代码来定而不是由每个人的电脑环境来定。只要package.json里写清楚packageManager新人拉代码跑第一条yarn命令的时候Corepack 就会自动帮他准备好正确的版本。这比让每个人“自己装一个吧”要省心得多。