说实话我一直觉得“怎么下载安装yarn”这种问题属于那种看起来简单、实际上特别容易翻车的入门操作。你去搜教程会看到一大堆说法有的让你直接npm install yarn有的让你去官网下安装包还有的让你开 Corepack——结果你跟着做装完敲yarn -v提示 command not found或者版本莫名其妙是老的 1.x项目里新语法全不认识更有甚者Windows 上装了之后在 PowerShell 里能用一开 Git Bash 又找不到了。这些坑我都踩过所以干脆把整个安装流程拆开了揉碎了写一篇从环境检查到三平台安装再到验证、换源、排错一次都说清楚。这篇东西适合三类人刚接触前端生态的初学者、被 npm 慢速折磨想尝试 Yarn 的开发者、以及在团队里负责初始化环境想少走弯路的人。1. 安装Yarn之前先搞清这三个问题1.1 Yarn到底是npm的替代品还是增强版Yarn 是 Facebook 团队在 2016 年开源的 JavaScript 包管理器。在那之前npm 几乎是唯一的选择但缺点也很明显安装依赖慢、依赖树不稳定、安全性存在隐患。Yarn 刚出来的时候主打三个卖点离线缓存、确定性依赖、并行安装。说白了就是“我比 npm 快、我比 npm 稳”。但今天你再问这个问题答案已经变得微妙了。npm 从 5.0 开始引入了package-lock.json锁文件也有了npm 7 之后又引入了 workspace性能也在慢慢追赶。那 Yarn 还值不值得装我的看法是如果你所在的项目已经用 Yarn或者你希望享受到 BerryYarn 2/3/4带来的 PlugnPlay 极致启动速度那 Yarn 完全值得。如果你是纯新项目、单打独斗、没有历史包袱用 npm 也没问题但了解 Yarn 的安装和用法依然是前端基本功。这里有个容易误解的点Yarn 并不是单纯替代 npm它重新定义了依赖管理的某些玩法。比如 Yarn Berry 的.pnp.cjs模式可以把 node_modules 彻底干掉依赖安装时间直接省掉一大半。但这些东西的前提是——你得先把 Yarn 装好。1.2 选Classic版还是Berry版——版本决策这是我在指导别人时一定会反复强调的问题。Yarn 的版本分裂非常严重Yarn Classic1.x最老的稳定版大多数老项目、老教程都在用它。命令是yarn install、yarn add锁文件为yarn.lock行为跟 npm 比较接近。Yarn Berry2.x 及以上2018 年底开始推出的新架构默认启用 PlugnPlayPnP打开.yarnrc.yml配置文件。很多命令行为变了还强调“Zero-Install零安装”。很多新手装完 Yarn发现版本是 1.22.x以为自己装错了又开始折腾。其实没装错只是npm install yarn默认给你的就是 Classic。而如果你用 Corepack 启用 Yarn默认给你的通常是 Berry。那到底选哪个我的建议使用场景推荐版本理由维护老项目锁定 Yarn Classic1.22.x兼容性最好不会造成意外升级新项目 / 愿意尝试新特性Berry3.x/4.x安装更快磁盘占用更少长期看是趋势公司统一环境 / 团队协作跟随项目锁文件packageManager字段声明什么就装什么所以安装之前先问一句你要装在哪个项目里如果没有特别需求我会直接建议你装 Berry然后用 Corepack 管理这样以后每个项目还能按需切换版本。1.3 硬性前提Node.js环境你怎么都躲不开无论你用什么方式装 Yarn都绕不开 Node.js。因为 Yarn 本身是一个 Node.js 程序运行时需要 Node 环境。所以安装 Yarn 之前必须先确保系统里有 Node.js并且注意版本要求Yarn Classic 1.x 一般要求 Node 10.0.0Yarn Berry 4.x 要求 Node 16.0.0推荐 18.0.0部分新特性比如某些 workspace 语法甚至要求 Node 20。检查方法很简单终端里输入node -v npm -v如果你发现连node都提示找不到那就先去 Node.js 官网 下载 LTS 版装上。这里要插一句不要直接去系统盘乱放文件Windows 建议用安装包一路下一步macOS 建议用nvm管理Linux 建议通过包管理器安装 NodeSource 源。Node 装好了Yarn 才谈得上安装。顺便说一句你有没有想过为什么会有“用 npm 装 yarn”这种操作因为 npm 是 Node.js 自带的包管理器而 Yarn 也是一个 npm 包所以理论上通过 npm 一条命令就能全局安装 Yarn。这个方式最通用但也有一些细节后面详细说。2. 三平台安装Yarn的正确姿势2.1 最通用通过npm全局安装适合已有Node的场景如果你已经确认 Node 没问题最简单的安装方式是通过 npm 全局安装 Yarn Classicnpm install -g yarn执行完之后终端会跑一段进度条结束后可以验证yarn -v如果输出1.22.x恭喜Classic 版已经装好了。这个方式的优点是通用Windows、macOS、Linux 全部适用缺点是默认装的是 Classic不是 Berry而且全局安装的东西有时候会跟系统权限、版本管理工具产生冲突。还有一种更现代的通用方式是使用 Node.js 官方推进的 Corepack。Node.js 从 16.9 开始内置了 Corepack所以如果你的 Node 版本足够新可以直接执行corepack enable然后会自动激活默认的 Yarn通常是 Berry。接着在项目目录里你可以指定版本corepack prepare yarnlatest --activate用这种方式的好处是 Yarn 的版本能够跟着项目走。如果项目根目录下有packageManager字段比如packageManager: yarn4.5.0Corepack 会自动下载对应版本并使用团队协同再也不用担心版本不一致。但注意 Corepack 在中国大陆的网络环境下首次下载可能较慢需要耐心等待或配置代理这个我们放在报错那节再细聊。2.2 Windows用户推荐的安装方式Windows 下安装 Yarn 有几个选择我按推荐度排序方式一通过 npm 全局安装最省事跟上面一样先打开命令提示符或 PowerShell建议“以管理员身份运行”避免权限问题然后npm install -g yarn装完以后yarn命令会出现在 npm 全局 bin 目录中默认是C:\Users\你的用户名\AppData\Roaming\npm。绝大多数情况下这个目录已经加入 PATH所以直接能用。方式二通过 Corepack 启用适合 Node 16.9 的用户PowerShell 里运行corepack enable注意如果你的 Node 是用官方 Windows 安装包装的Corepack 通常没问题。但如果 Node 是通过某些第三方工具如 nvm-windows装的个别版本可能没有带 Corepack那就需要手动安装一下npm install -g corepack方式三下载官方安装包适合不爱命令行的人到 Yarn 官网下载.msi安装包双击安装。这种方式会把 Yarn 安装到系统目录并且自动配好 PATH。但有个麻烦官方安装包版本停留在 Classic 1.22且不会跟随版本更新所以不推荐经常升级的人使用。Windows 安装完最常遇到的问题就是“在 PowerShell 里能用在 Git Bash 里不能用”。原因很简单Git Bash 使用的 PATH 跟 Windows 系统 PATH 不一致或者是命令别名冲突。解决方式是在 Git Bash 里直接调用完整路径或者把 npm 全局目录加到 Git Bash 的 PATH 中。这些细节在踩坑章节里展开。2.3 macOS用户推荐的安装方式macOS 用户我强烈建议先安装 Homebrew然后用 Homebrew 装 Yarn省心且便于卸载brew install yarn这个命令会顺手安装 Node如果还没有的话然后把 Yarn Classic 装好。验证一下brew list yarn yarn -v如果你想要装 Berry可以借助 Corepackbrew install corepack corepack enable另一个常见做法是通过nvm管理 Node再用 npm 全局安装 Yarn。这样做的优势是 Node 版本可以自由切换Yarn 也跟着不同 Node 版本走。我个人的经验是macOS 下不要用 sudo 去执行npm install -g否则各种 EACCES 权限错误会把你整疯。如果遇到权限错误正确的做法是给当前用户共享 npm 全局目录或用 nvm。2.4 Linux/服务器环境用npm和Corepack都不踩坑Linux 用户分两种情况一是自己的开发机二是无图形界面的服务器CI 环境。开发机如果用的是 Ubuntu/Debian可以直接走 npmsudo apt update sudo apt install nodejs npm sudo npm install -g yarn但这里有个隐藏问题Ubuntu 自带的 nodejs 版本通常比较老可能导致 Yarn 运行时报不支持。所以更稳的做法是先安装 NodeSource 源拿到较新的 Node再装 Yarn。如果用的是 CentOS/RHEL 系可以用 dnfsudo dnf install nodejs sudo npm install -g yarn对于 CI 场景尤其是 Docker 镜像我建议用 Corepack因为可以通过环境变量精确控制 Yarn 版本。比如 Dockerfile 里写RUN corepack enable corepack prepare yarn4.5.0 --activate这样镜像里就固定了 Yarn 版本避免“本地好好的一进 CI 报错”的尴尬。3. 装完不等于结束验证、升级、卸载与镜像加速3.1 安装后的第一件事验证版本与命令路径吃饱了没事干先别急着用先执行验证三连yarn -v which yarn # Windows 上是 where yarn yarn --versionwhich yarn的目的是看命令是从哪里来的。这一步非常有价值。比如你发现输出是/usr/local/bin/yarn说明安装路径正常如果输出是C:\Program Files\nodejs\yarn说明跟 Node 装在了一起如果输出“没有这个命令”那说明 PATH 没配好。接下来建议执行一条真正的安装命令测试是否真的能工作。随便找个目录初始化一下yarn init -y yarn add lodash如果yarn add能顺利下载 lodash 并生成node_modules和yarn.lock那说明整个链路是通的。这一步比单纯yarn -v更靠谱因为有些环境里命令能找到但下载依赖时会因为网络问题挂掉。3.2 把Yarn设为默认包管理器很多人装了 Yarn 之后还是会惯性地敲npm install时间长了就混用、冲突。我的建议是在每个项目开始时就想清楚到底用哪个包管理器然后锁死。Yarn Classic 会在项目根目录生成yarn.locknpm 会生成package-lock.json。如果一个项目里两个锁文件都存在依赖版本就很容易对不上排查起来非常痛苦。如果你是 Yarn Berry 用户可以直接在package.json里写{ packageManager: yarn4.5.0 }以后任何人进入这个项目运行corepack enable后就会自动使用正确的 Yarn 版本。这就是 Yarn 官方最推崇的“管理方式”。如果希望系统层面的默认命令也指向 Yarn可以把全局包管理器设置为 Yarnnpm config set package-manager yarn但其实这个设置只影响部分 npm 脚本的解析并不是真正意义上的默认包管理器。真正常用的做法是在项目里配置scripts把install脚本直接写成yarn install或者干脆约定成俗。3.3 国内网络环境下必须配置的镜像源老实说Yarn 安装成功只是第一步真正卡住 90% 新手的是下载依赖时龟速网络。如果你在国外或服务器有代理可以跳过本节但如果你的网络环境访问官方 registry 很慢强烈建议换成淘宝镜像源。Yarn 1.x 设置镜像yarn config set registry https://registry.npmmirror.comYarn Berry2.x设置镜像yarn config set npmRegistryServer https://registry.npmmirror.com这里有个容易踩的坑Yarn 1.x 用的是.npmrc或全局配置Yarn Berry 会把配置写进项目里的.yarnrc.yml。如果你把 Yarn 1 的配置命令用在 Berry 上虽然不报错但实际可能不生效因为配置键名不一样。我测过国内网络环境下换源后安装速度可以从几分钟降到几秒钟。所以装完 Yarn 后第一件事就是换源特别是用默认源经常报 ETIMEDOUT 或者 TLS 相关错误的时候。3.4 卸载Yarn的干净方法有时候想卸掉重装或者觉得 Yarn 版本不干净。卸载同样要看安装方式用 npm 装的npm uninstall -g yarn用 Corepack 激活的corepack uninstall yarn或在项目中禁用corepack disable用 Homebrew 装的brew uninstall yarn用官方安装包的到控制面板/软件管理里卸载。卸完还要检查残留的 yarn 缓存目录吗一般不用。缓存目录是~/.yarn/cacheBerry 是项目下.yarn/cache卸载后缓存可以留着以后重装时重新依赖解析速度会更快。但如果磁盘紧张也可以手动删掉。这里提醒一个细节如果你曾经通过 npm 装过 yarn后来又用 Corepack 启用了 yarn可能会出现“yarn 命令指向两个版本”的诡异现象。排查方法还是前面说的分别运行which yarn和yarn -v确认当前生效的是哪一个。通常建议彻底卸载其中一个来源避免版本混乱。4. 安装过程中最常见的七种报错与排查链路这一章我想用一个真实的排查过程串联起来因为你只背报错信息没用得学会排查思路。以前我帮一个朋友在 Windows 上装 Yarn他用的 npm报错是yarn 不是内部或外部命令也不是可运行的程序或批处理文件。于是我们开始一步步排查。4.1 一次真实的“Command not found”排查过程第一步检查 npm 是否安装成功npm -v正常。第二步查看 npm 全局 bin 目录位置npm bin -g # Windows 上输出类似 C:\Users\xxx\AppData\Roaming\npm第三步查看这个目录下有没有yarn或yarn.cmddir C:\Users\xxx\AppData\Roaming\npm\yarn*发现根本没有 yarn 相关文件。说明 npm install 时虽然显示成功但实际文件没落盘。为什么没落盘大概率是权限问题或者 npm 缓存损坏。于是我们执行npm install -g yarn --force这次报了另一个错误Unexpected end of JSON input。这个报错的意思是 npm 读取缓存时数据不完整。解决方法是清缓存npm cache clean --force然后再次安装这下成功了。这个排查链路的关键是先确认文件到底存不存在别在 PATH 里瞎折腾。很多“命令找不到”根本不是 PATH 问题而是安装根本没成功。你可以用npm root -g查看全局包根目录再手动查看有没有 yarn 子目录一般能直接看出问题。4.2 “Corepack is not found”背后的Node版本问题第二种常见报错是corepack: command not found甚至有人运行corepack enable时提示“无法加载程序包”。这大概率是 Node 版本太老。Corepack 是在 Node 16.9 之后才内置的Node 14 以及旧版本没有。如果你必须用旧版 Node那就别纠结 Corepack直接走 npm 全局安装 Yarn 就好。但如果你用的是 nvm 这种多版本管理器装了两个 Node一个 18一个 14那你终端里的 corepack 可能来自第一个 Node 的 bin 目录而当前激活的是第二个 Node就会找不到。解决方式nvm use 18 corepack enable或者手动安装 Corepacknpm install -g corepack这里还有个小坑Windows 上 corepack 和 yarn 一样会出现.cmd文件与 bash 脚本不通用的问题。在 Git Bash 里运行corepack enable可能提示一堆不认识的命令此时可以尝试在 PowerShell 里执行或者把C:\Program Files\nodejs下的corepack.cmd所在的目录加到 Git Bash 的 PATH 前面。4.3 网络超时与证书报错的解决办法如果安装时一直卡在Waiting for the migration...或ETIMEDOUT一般都是网络问题。还有一种变体是request to https://registry.yarnpkg.com/... failed, reason: getaddrinfo ENOTFOUND registry.yarnpkg.com这个报错的意思是 DNS 解析不了registry.yarnpkg.com。在某些地区这个域名访问质量很差。解决办法就是前面说的换源yarn config set registry https://registry.npmmirror.com如果是 Yarn Berry 安装时的 Corepack 下载超时可以手动指定镜像COREPACK_NPM_REGISTRYhttps://registry.npmmirror.com corepack prepare yarn4.5.0 --activate还有证书报错比如Self-signed certificate in certificate chain这通常是公司局域网开了 HTTPS 拦截或某个工具篡改了证书。解决办法有两种思路一是配置严格的安全策略二是把 npm 的 strict-ssl 关掉。如果是自己公司网络问一下管理员拿根证书如果是为了临时解决问题可以npm config set strict-ssl false但我不建议长期关闭 SSL 校验这会让依赖包被篡改的风险上升。更好的做法是确保系统时间准确因为证书报错有时候也是“系统时间不对”导致的。4.4 权限不足EACCES的处理思路这个坑在 macOS 和 Linux 上非常常见。当你执行npm install -g yarn却看到Error: EACCES: permission denied, access /usr/local/lib/node_modules说明 npm 全局目录需要管理员权限。常规做法是加sudosudo npm install -g yarn但一直用sudo真的不是什么好事——每次装包都要输入密码不说还会导致全局目录里的文件悲剧地变成 root 所有下次升级没权限又得 sudo。更好的方式是把 npm 全局目录改成当前用户可写的目录比如mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH然后不用 sudo 直接npm install -g yarn。这条经验来自我自己踩过的坑在 macOS 上用这个方式后再也没遇到权限问题。4.5 其他值得留意的坑版本冲突系统里同时存在多个 Node 版本管理器nvm、fnm、volta导致 Yarn 安装到了 A Node 的全局目录而当前 shell 用的是 B Node于是找不到命令。检查方法which npm和which node的路径是否在同一个目录下。如果不在那大概率是环境变量的问题。包名混淆有人会误装成yarnpkg/cli。如果你看了某些文档运行了npm install -g yarnpkg/cli也行但命令会变成yarnpkg不是yarn。真要用 Berry应该通过 Corepack 或项目目录启用。防火墙限制企业内部网络可能禁止访问某些海外域名导致 Yarn 安装依赖一直卡住。解决办法就是换内网 registry 或企业私服。PATH 顺序问题当你装了多个版本yarn命令可能被另一个目录下的旧版本覆盖。检查which -a yarn可以看到所有候选路径然后调整 PATH 顺序即可。项目级配置污染如果你在某个项目里运行过yarn set version berry它会在项目里生成一个.yarnrc.yml把 Yarn 版本锁定为 Berry。哪怕你全局装的是 1.x在这个项目里运行yarn -v显示的也是项目版本。这是正常现象不是出错了。5. 从npm切换到Yarn后的实用命令对照与项目体验5.1 新手最常用的14个命令对照表装好之后就要用了。我整理了一份常用命令对照方便你从 npm 平滑切换过来功能npmYarn 1.xYarn Berry初始化项目npm init -yyarn init -yyarn init -y安装全部依赖npm installyarn installyarn install添加生产依赖npm install lodashyarn add lodashyarn add lodash添加开发依赖npm install -D eslintyarn add -D eslintyarn add -D eslint删除依赖npm uninstall lodashyarn remove lodashyarn remove lodash更新依赖npm updateyarn upgradeyarn up lodash运行脚本npm run devyarn run devyarn run dev或yarn dev全局安装npm install -g yarnyarn global add xxxyarn dlx发布包npm publishyarn publishyarn npm publish查看依赖树npm lsyarn listyarn info缓存清理npm cache clean --forceyarn cache cleanyarn cache clean创建软链接npm linkyarn linkyarn link交互式升级npm outdatedyarn outdatedyarn outdated执行一次性命令npxyarn add --dev临时yarn dlx看到区别没大方向上通用细节有差异。最需要注意的就是 Berry 不再支持yarn global add而是推荐使用yarn dlx来执行工具。如果你还在生搬硬套老教程第一次跑就会报错。5.2 项目迁移时的注意点把一个 npm 项目迁到 Yarn不是简简单单删除package-lock.json然后跑yarn install就行的因为我见过太多人在这翻车。首先检查现有依赖的版本锁定情况。npm 的package-lock.json记录了精确版本但 Yarn 会自己生成yarn.lock。在迁移前最好先确保package.json里的依赖范围是合理的否则 Yarn 解析出来的版本可能会改变导致某些依赖在升级后出现兼容问题。其次注意有无原生模块比如 node-sass、sharp、bcrypt。这类模块需要本地编译Yarn Classic 和 Berry 对它们的处理方式不同。Berry 默认 PnP 模式可能让某些工具收集依赖的方式失效所以遇到这类模块时可以关闭 PnPyarn config set nodeLinker node-modules在项目根目录的.yarnrc.yml里加上nodeLinker: node-modules然后重新yarn install会退回用 node_modules 目录兼容性好很多。等熟悉了再研究 PnP 也不迟。第三注意scripts里的NPM_CONFIG_REGISTRY等环境变量。Yarn 不一定读取 npm 的.npmrc中所有字段所以之前配置的一些特殊环境变量可能要迁移到 Yarn 的配置文件中。5.3 一些真实存在但文档里不太显眼的优化细节安装完成、能正常下载依赖这只是“能用”。分享几个我用下来觉得很关键的优化点。第一配置离线缓存目录。Yarn 会把依赖包存到全局缓存下次安装时即使断网也能从缓存装。默认缓存目录在~/.yarn/cache或.yarn/cache。如果你经常在不同机器间切换可以把缓存目录放到一个共享网盘极大提升切换速度yarn config set cache-folder /path/to/shared/cache第二为项目固定 Yarn 版本。我前面提到packageManager字段这里再细说。在项目里执行yarn set version 4.5.0它会修改.yarnrc.yml和package.json并把 Yarn 源码放到.yarn/releases目录。这样团队里其他人 clone 项目后只需要运行corepack enable yarn --version就能自动使用项目版本。这就是“零配置协作”的雏形。第三善用yarn dlx。以前用npx执行临时工具Yarn Berry 对应的是yarn dlx。比如想跑create-viteyarn dlx create-vite my-app它会临时安装工具、运行、然后清理不会污染项目依赖。这个体验比全局装工具或者npx在部分场景下更干净。第四关注.gitignore。Yarn Berry 的 Zero-Install 模式下.yarn/cache目录很大通常建议把它忽略掉。而普通模式又需要提交yarn.lock。所以一定要根据你的项目情况配置.gitignore不要盲目复制别人的模板。我的习惯是Classic 忽略 node_modules保留 yarn.lockBerry 忽略 node_modules、.yarn/cache、.pnp.*保留 .yarnrc.yml。6. 说在最后一套真正顺畅的安装流程把前面的内容压缩成一套流程方便你照做。以我日常最推荐的组合为例Node 18 通过 nvm 安装Corepack 启用 Yarn Berry。第一步检查 Nodenode -v第二步启用 Corepackcorepack enable第三步在项目目录里锁定版本yarn set version stable第四步设置镜像yarn config set npmRegistryServer https://registry.npmmirror.com第五步安装依赖yarn install这套流程在 Windows、macOS、Linux 上都适用也是我目前团队用的方案。如果你的团队还在用 Yarn Classic那就把第三步去掉直接用npm install -g yarn或 Homebrew 安装即可。有人可能想问“装完 Yarn 后到底图个啥”我的实际感受是单看安装依赖的速度现在 npm 和 Yarn 的差距已经没有 2016 年那么悬殊了但 Yarn Berry 的 PnP 模式带来的启动提速、零安装体验以及项目级版本锁定带来的确定性依然是我选择它的核心理由。尤其是大型 monorepo 项目Yarn Berry 的缓存和 workspace 支持真的能让你省出大把时间。最后提一句如果安装过程中遇到没见过的新报错别急着卸载重装。先运行yarn -v确认版本再运行yarn config list查看配置然后把报错原文复制到搜索引擎。只要命令路径、Node 版本、网络源这三个基本盘没问题90% 的安装问题都能自己解决。这也是我这几年折腾前端工具链最大的体会。