1. 为什么 Mac 上装 Yarn 这件事值得单独写一篇很多人看到Mac 安装 yarn这个标题第一反应是不就一行命令的事吗npm install -g yarn敲下去不就完了我一开始也这么想直到我在三台不同芯片、不同系统版本的 Mac 上反复折腾才发现这件事的坑远比想象中多。尤其是 Apple Silicon 芯片普及之后Node 版本管理工具、包管理器、全局路径、权限这几件事搅在一起新手很容易装完发现命令找不到、版本对不上、或者装到一半报权限错误。Yarn 是什么简单说它是 JavaScript 生态里的一个包管理工具和 npm 干的是同一件事——帮你下载、管理项目依赖。它最早由几家大厂联合推出主打速度快、依赖锁定可靠、支持离线缓存。虽然现在 npm 本身也进步了很多pnpm 也分走了不少用户但 Yarn 在大量存量项目里依然是标配尤其是那些用 Yarn Workspaces 做 monorepo 的工程。所以不管你是刚入门前端的新手还是接手老项目的开发者在 Mac 上把 Yarn 装好、装对都是一件绕不开的事。这篇内容我会从芯片架构差异、安装方式选型、版本管理、常见报错排查几个角度把这件事彻底讲透。适合三类人看一是刚买 Mac 准备学前端的同学二是装了 Yarn 但总出问题的开发者三是想搞清楚 Yarn 和 npm、pnpm 到底该怎么选的人。我不会只给你一行命令就完事而是把每一步背后的原因讲清楚让你装完之后心里有底出了问题也能自己排查。先说一个反直觉的结论在 Mac 上装 Yarn最不推荐的方式恰恰是很多人最先想到的npm install -g yarn。为什么往下看。2. 装之前先搞清楚你的 Mac 是什么芯片、Node 从哪来2.1 Apple Silicon 和 Intel 芯片的路径差异从 2020 年之后Mac 分成了两条线老的 Intel 芯片和新的 Apple SiliconM 系列芯片。这件事对装 Yarn 的影响比大多数人以为的要大。核心差异在于二进制依赖的架构。Yarn 本身是 JavaScript 写的理论上跨架构没问题但它依赖的 Node 运行时是分架构的。如果你在 M 系列芯片上装了一个 x86 架构的 Node比如通过 Rosetta 转译运行的旧版本那么基于它安装的 Yarn 也可能跑在转译层里速度慢不说还容易出现原生模块编译失败的问题。怎么确认自己的芯片打开终端敲uname -m输出arm64你是 Apple Silicon走原生 arm64 路线。输出x86_64你是 Intel 芯片或者你的终端正跑在 Rosetta 转译模式下。这里有个隐藏坑有些人的终端本身被设置成了 Rosetta 模式导致uname -m显示x86_64但机器其实是 M 系列。检查方法是在访达里找到终端应用右键显示简介看有没有勾选使用 Rosetta 打开。如果有取消勾选重启终端再测一次。为什么要在意这个因为如果你的 Node 是 x86 版本装出来的 Yarn 在调用某些原生依赖时会出现架构不匹配的报错典型症状是mach-o file, but is an incompatible architecture。这个错误我在帮别人排查时遇到过好几次根源就是架构混用。2.2 Node 的来源决定了 Yarn 怎么装Yarn 是跑在 Node 之上的所以先有 Node才有 Yarn。而 Node 在 Mac 上的安装方式直接决定了你该用哪种方式装 Yarn。常见的 Node 安装方式有三种安装方式特点对装 Yarn 的影响官网 pkg 安装包简单直接但全局包路径固定切换版本麻烦用npm -g装 Yarn 会装到系统级路径可能需要 sudoHomebrew方便管理但 Node 版本更新频繁可以用 brew 直接装 Yarn但版本可能滞后nvm / fnm 等版本管理器可自由切换 Node 版本路径隔离干净推荐配合corepack或npm -g无需 sudo我的建议很明确如果你还没装 Node先装一个版本管理器nvm 或 fnm再用它装 Node最后装 Yarn。这样全局包路径都在你的用户目录下不需要 sudo切换 Node 版本时 Yarn 也跟着走干净利落。如果你已经用官网 pkg 装了 Node也别急着卸载可以先看看当前 Node 版本和路径which node node -v npm -vwhich node的输出能告诉你 Node 装在哪。如果是/usr/local/bin/node或/opt/homebrew/bin/node说明是系统级或 brew 级安装如果是/Users/你的用户名/.nvm/...这种说明是版本管理器装的。2.3 一个容易被忽略的前置检查npm 全局路径权限不管你最后用哪种方式装 Yarn都建议先检查一下 npm 的全局路径权限。很多人装 Yarn 时报EACCES: permission denied根源就在这里。npm config get prefix如果输出是/usr/local或/usr那说明全局包会装到系统目录普通用户没写权限就会报权限错误。正确的做法是把 prefix 改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。在~/.zshrcMac 默认 shell 是 zsh末尾加一行export PATH~/.npm-global/bin:$PATH执行source ~/.zshrc生效。这一步做完后面装 Yarn 就不会再被权限问题卡住了。这个操作看起来是额外步骤但它能帮你避开后面 80% 的报错非常值得。3. 四种安装方式实测对比哪种最适合你3.1 方式一corepackNode 16.10 官方推荐从 Node 16.10 开始官方内置了一个叫corepack的工具专门用来管理 Yarn 和 pnpm 这类包管理器的版本。这是目前最推荐的方式原因是它把 Yarn 的版本和项目绑定而不是全局装一个固定版本。启用方式corepack enable如果提示command not found说明你的 Node 版本太老或者 corepack 没被激活。可以先检查node -vNode 16.10 以上才有 corepack。如果版本够但还是找不到可能是安装 Node 时没带上 corepack这种情况建议换用版本管理器重装 Node。启用之后在项目目录里可以直接指定 Yarn 版本corepack prepare yarnstable --activate或者更精细地指定corepack prepare yarn4.1.0 --activatecorepack 的好处是每个项目可以用不同的 Yarn 版本通过项目根目录的packageManager字段自动切换。比如你在package.json里写{ packageManager: yarn4.1.0 }那么进入这个项目时corepack 会自动使用 4.1.0 版本完全不用手动切换。这对维护多个老项目的开发者来说简直是救星。不过 corepack 也有个坑它默认可能没在 PATH 里注册 yarn 命令需要先corepack enable一次。另外某些 Node 版本尤其是通过某些包管理器装的可能没带 corepack这时候就得手动补。3.2 方式二npm 全局安装最传统但要注意路径这是最广为人知的方式npm install -g yarn如果你前面已经把 npm prefix 改到了用户目录这条命令会顺利执行Yarn 会装到~/.npm-global/bin/yarn。验证yarn -v能输出版本号就成功了。但这种方式有两个问题。第一它装的是 Yarn 1.xClassic还是 2.xBerry取决于 npm 源里的 latest 标签你没法精确控制。第二全局只有一个版本切换项目时如果项目要求不同版本就会冲突。所以我的看法是npm 全局安装适合只想快速用一下、不涉及多版本切换的场景。如果你要长期做前端开发还是 corepack 更靠谱。3.3 方式三Homebrew 安装适合 brew 重度用户如果你习惯用 Homebrew 管理一切那可以brew install yarnHomebrew 会自动处理依赖把 Yarn 装到/opt/homebrew/binApple Silicon或/usr/local/binIntel。但这里有个非常容易踩的坑brew install yarn有时会顺带装一个 Node 依赖导致你系统里出现两个 Node——一个是你自己装的一个是 brew 装的。两个 Node 路径不同npm 全局包也各管各的最后yarn命令用的是哪个 Node 都搞不清。验证方法which -a node which -a yarn如果输出多行说明有多个版本共存。这时候要么统一用 brew 管理要么把 brew 装的 Node 卸载掉brew uninstall node只保留版本管理器装的。另外Homebrew 的 Yarn 版本更新通常比官方慢半拍如果你需要最新特性可能等不到。3.4 方式四独立脚本安装不推荐仅作了解Yarn 官方早期提供过一个安装脚本通过 curl 下载执行。这种方式现在基本被 corepack 取代了而且脚本安装的版本管理很麻烦我不建议用。这里提一句只是让你知道有这么回事遇到老教程提到时能分辨。3.5 四种方式横向对比方式优点缺点推荐场景corepack版本随项目切换官方推荐无需 sudo需要 Node 16.10初次配置略繁琐长期开发多项目并存npm 全局命令简单人人会版本固定可能需改 prefix快速试用单一项目Homebrew与 brew 生态统一可能引入重复 Node版本滞后brew 重度用户独立脚本无需 Node管理混乱已过时不推荐看完这张表结论很清楚能上 corepack 就上 corepack实在不行用 npm 全局但记得改 prefixbrew 只在你有明确理由时用。4. 装完之后必须做的三件验证事4.1 验证命令可用性和版本装完第一件事别急着跑项目先确认命令真的能用yarn -v如果报command not found说明 PATH 没配好。回到前面检查~/.zshrc里的 PATH 配置确认~/.npm-global/bin或 corepack 的 shim 路径在里面。如果输出了版本号比如1.22.22或4.1.0说明命令通了。这里要注意区分Yarn 1.x 和 Yarn 2它们的命令行为差异很大。1.x 是经典版2 是所谓的 Berry 版配置文件、锁文件格式都不一样。4.2 确认 Yarn 用的是哪个 Node这一步很多人忽略但非常关键yarn node -v这条命令会告诉你 Yarn 实际调用的 Node 版本。如果这个版本和你node -v看到的不一致说明 Yarn 和 Node 来自不同的安装源后面很可能出问题。理想情况下两者应该一致。如果不一致检查是不是有多个 Node 共存用which -a node排查。4.3 检查全局缓存和配置目录Yarn 会在用户目录下建缓存和配置yarn cache dir yarn config listyarn cache dir告诉你缓存位置默认在~/Library/Caches/Yarn或类似路径。如果这个目录权限有问题装包时会失败。yarn config list列出当前所有配置能帮你确认 registry 等关键项是否正确。提示如果你在国内网络环境下遇到下载慢的问题可以配置镜像源。但具体配置请参考官方文档我这里不展开避免给出过时信息。5. 那些年我踩过的 Yarn 安装坑5.1 坑一command not found 的三层排查yarn: command not found是最常见的报错但原因可能有三层得逐层排查。第一层PATH 没包含 Yarn 所在目录。用echo $PATH看输出里有没有 Yarn 的安装路径。没有的话把对应路径加进~/.zshrc。第二层shell 配置文件没生效。改完~/.zshrc后必须source ~/.zshrc或者重开终端。有些人改了文件但没生效以为没配对。第三层装到了错误的 shell 配置里。Mac 默认是 zsh但有些人之前用过 bash把 PATH 写进了~/.bash_profile。zsh 启动时读的是~/.zshrc两者不互通。确认你改的是当前 shell 对应的文件用echo $SHELL看当前 shell。这三层排查下来基本能定位所有 command not found 问题。5.2 坑二权限报错的根治方法EACCES: permission denied这个错误本质是 npm 想往系统目录写文件但没权限。很多人第一反应是加sudosudo npm install -g yarn千万别这么干。用 sudo 装全局包会让文件属主变成 root后续普通用户操作时又会报权限错误陷入死循环。正确做法是前面说的改 prefix 到用户目录一劳永逸。如果已经用 sudo 装过了得先把属主改回来sudo chown -R $(whoami) ~/.npm-global然后再按正常流程操作。5.3 坑三架构不匹配的诡异报错在 M 系列芯片上如果你看到类似这样的报错mach-o file, but is an incompatible architecture (have x86_64, need arm64)说明你的 Node 或某个依赖是 x86 架构的但系统期望 arm64。根源通常是 Node 装错了架构。解决办法是卸载现有 Node用版本管理器重装 arm64 版本。用 nvm 的话nvm uninstall 版本号 nvm install 版本号nvm 会自动根据当前架构下载对应版本。装完再重装 Yarn问题就解决了。5.4 坑四Yarn 1 和 Yarn 2 的命令差异很多人装完发现命令行为和教程对不上原因是版本不同。Yarn 1.x 和 2 有几个关键差异操作Yarn 1.xYarn 2初始化yarn inityarn init -2或自动添加依赖yarn add xxxyarn add xxx类似全局安装yarn global add xxx不再支持 global用yarn dlx锁文件yarn.lockyarn.lock格式不同配置.yarnrc.yarnrc.yml最典型的是Yarn 2 取消了yarn global add改用yarn dlx临时执行。如果你照着老教程敲yarn global add在 2 上会报错。搞清楚自己用的是哪个大版本能省下大量困惑时间。5.5 坑五corepack 启用后 yarn 命令反而没了这个坑比较隐蔽。有些人启用 corepack 后发现原来的yarn命令不见了。原因是 corepack 接管了 yarn 命令但需要项目里有packageManager字段才会激活对应版本。在没配置的项目里可能提示找不到版本。解决办法是在项目里显式指定corepack use yarnstable这条命令会写入packageManager字段并激活。之后yarn -v就正常了。6. Yarn、npm、pnpm 到底该怎么选6.1 三者的核心差异装 Yarn 的过程中很多人会问现在 npm 这么好用pnpm 又这么快我为什么还要用 Yarn这个问题值得说清楚。维度npmYarnpnpm依赖存储扁平化 node_modules扁平化1.x/ PnP2硬链接 内容寻址安装速度中等快最快磁盘占用高高低共享存储锁文件package-lock.jsonyarn.lockpnpm-lock.yamlmonorepo 支持workspacesworkspaces成熟workspaces生态兼容最好好偶有兼容问题简单说npm 是默认选项兼容性最好Yarn 在 monorepo 和依赖锁定上更成熟pnpm 在速度和磁盘占用上最优但个别老包可能不兼容。6.2 什么情况下必须用 Yarn有三种情况你基本没得选必须用 Yarn第一项目里已经有 yarn.lock。锁文件决定了依赖的精确版本用 npm 或 pnpm 装会生成不同的锁文件可能导致依赖版本漂移引发莫名其妙的 bug。第二项目用了 Yarn Workspaces 做 monorepo。虽然 npm 和 pnpm 也有 workspaces但老项目的配置是按 Yarn 写的换工具要改配置。第三团队规范要求。有些团队统一用 Yarn你跟着用就行别自作主张。6.3 我的实际选择建议就我个人经验新项目我会优先考虑 pnpm因为速度和磁盘优势明显。但如果是接手存量项目项目用什么我就用什么绝不轻易换包管理器。换包管理器的成本远大于那点速度收益而且容易引入难以排查的依赖问题。Yarn 的定位现在有点尴尬夹在 npm 和 pnpm 之间。但它的 Workspaces 和 PnPPlugnPlay机制依然有独特价值尤其是 PnP 那种不生成 node_modules 的方案在大型 monorepo 里能显著提升安装速度。所以学 Yarn 不算过时只是要清楚它的适用边界。7. 装好之后几个提升效率的配置7.1 配置镜像源加速下载网络环境不理想时下载依赖会非常慢。Yarn 支持配置 registryyarn config set registry 镜像地址具体镜像地址请以官方或可信渠道公布的信息为准我这里不写死避免过时。配置后可以用yarn config get registry确认。7.2 开启全局缓存复用Yarn 默认就有缓存机制重复安装同一个包时会从缓存读取。确认缓存开启yarn config get enableGlobalCache如果是true说明全局缓存已启用。这个机制能大幅减少重复下载尤其在多个项目共用相同依赖时效果明显。7.3 用 .yarnrc.yml 做项目级配置Yarn 2 用.yarnrc.yml做项目配置可以针对单个项目设置 nodeLinker、registry 等。比如强制用 node_modules 模式而不是 PnPnodeLinker: node-modules这个配置对不熟悉 PnP 的团队很友好能避免一堆兼容性问题。放在项目根目录提交到版本库团队所有人共享。7.4 定期清理缓存缓存用久了会占空间定期清理yarn cache clean这条命令会清空缓存。如果只想看缓存占了多少空间可以先yarn cache dir找到目录用du -sh查看大小。我一般几个月清一次避免磁盘被占满。8. 关于版本升级和降级的实操8.1 从 Yarn 1 升级到 Yarn 2如果你项目还在用 Yarn 1想升级到 2官方提供了迁移命令yarn set version berry这条命令会下载最新稳定版并写入配置。升级后项目里会多出.yarn目录和.yarnrc.yml锁文件格式也会变。升级前务必提交代码或备份因为锁文件变化可能影响依赖解析。升级后如果遇到兼容问题可以回退yarn set version classicclassic就是 1.x 的代号。8.2 锁定特定版本避免意外升级团队协作时最怕每个人用的 Yarn 版本不一样。解决办法是在package.json里写死{ packageManager: yarn4.1.0 }配合 corepack任何人进项目都会自动用这个版本彻底消除版本差异。这个字段是 corepack 识别的关键强烈建议加上。8.3 卸载 Yarn 的正确姿势如果你要换包管理器得先把 Yarn 卸干净。根据安装方式不同卸载方法也不同npm 装的npm uninstall -g yarnbrew 装的brew uninstall yarncorepack 管理的corepack disable然后删掉相关配置卸完记得检查which yarn确认没有残留。有时候 PATH 里还留着旧路径需要手动清理~/.zshrc。9. 写在最后的一点个人体会折腾了这么多台 Mac、这么多种安装方式我最大的体会是装工具这件事慢就是快。花十分钟把 Node 的来源、PATH 的配置、芯片架构这些前置条件搞清楚比装完出问题再花两小时排查要划算得多。我见过太多人一上来就npm install -g yarn然后被权限、路径、版本问题轮番折磨最后对前端环境配置产生心理阴影。其实只要按先版本管理器装 Node再 corepack 管 Yarn这个顺序走整个过程会非常顺。另外提醒一句环境配置这东西没有一劳永逸的方案。系统升级、Node 大版本更新、Yarn 从 1 到 4 的演进都会带来新的变化。保持关注官方文档遇到报错先看错误信息里的关键词再针对性搜索比盲目试错高效得多。最后分享一个小习惯我会在~/.zshrc里加一行注释记录当前 Node 和 Yarn 的安装方式比如# Node via nvm, Yarn via corepack。过几个月回头看能立刻想起当初是怎么配的省去重新排查的麻烦。这个习惯帮我省了不少时间你也可以试试。