如何在现代 JavaScript 项目中安装和使用 Yarn

主页 » Python » 如何在现代 JavaScript 项目中安装和使用 Yarn

如果你正在尝试为你的 JavaScript 项目安装 Yarn，并且在众多选项中感到有些迷茫，你并不孤单。 Yarn 近年来发展迅速，它与 npm 共存，并且根据操作系统甚至项目风格（monorepo、PnP、经典 node_modules 等）的不同，有不同的版本和安装流程。

好消息是，一旦你了解了 Yarn 的安装方式以及它的两级模型（全局 CLI + 项目特定的 Yarn）的工作原理，一切都会变得有意义。 在本指南中，我们将详细介绍如何在最常见的系统上安装 Yarn，如何将其连接到真正的 JavaScript 项目中，它与 npm 的区别，以及如何解决首次使用时通常会遇到的典型问题。

Yarn 是什么以及它为何对 JavaScript 项目仍然重要

Yarn 是一个 Node.js 包管理器，其设计理念围绕三大目标展开：速度、安全性和确定性安装。 Yarn 诞生于 npm 存在性能和可靠性问题的时候，作为 npm 的替代方案。尽管 npm 从那时起已经有了很大的改进，但 Yarn 仍然非常流行，尤其是在 React 和现代前端技术栈方面。

Yarn 的主要优势之一是其确定性的安装过程，该过程基于 yarn.lock 文件中。 此文件修复了所有直接和传递依赖项的确切版本，以便在不同的机器或 CI 服务器上安装时始终产生相同的依赖关系树，从而消除经典的“它只在我的笔记本电脑上运行”的问题。

另一个显著特点是其积极的缓存行为，这使得 Yarn 可以重用它已经下载的任何包。 正因如此，重复安装的速度大大加快，如果所有必需的软件包都已预先缓存，Yarn 甚至可以在离线模式下工作。

Modern Yarn（2.x、3.x 和 4.x 版本通常被称为“Berry”）带来了即插即用 (PnP) 和工作区等高级功能。 PnP 可以完全消除传统 node_modules 通过将文件夹替换为清单文件，Node.js 可以精确地告诉每个包的位置，从而节省大量磁盘空间并加快某些操作。另一方面，工作区非常适合单体仓库，它将单个仓库中的多个包链接到共享的锁定文件和集中式依赖管理中。

从安全角度来看，Yarn 会在执行每个包之前验证其校验和。 这种完整性验证增加了一层额外的保护，防止数据被损坏或篡改，这在企业或敏感环境中尤其有用。

了解经典纱线与浆果纱线（现代纱线）的区别

在讨论安装之前，必须了解 Yarn 有两大系列：Classic (1.x) 和 Berry (2.x/3.x/4.x)。 Yarn Classic 保存在其独立的历史记录库中，仅接收安全修复，而所有活跃的开发工作都集中在托管于其中的更新的 Berry 系列上。 yarnpkg/berry 回购。

Yarn Classic（大约 1.22 版本）是大多数人在安装全局 Yarn 时仍然会得到的版本。 yarn 使用 npm 进行 CLI。 如今，全局 CLI 主要用作启动器：在已配置 Berry 的项目中，全局命令只是将执行委托给本地项目特定的 Yarn 版本，因此您可以在不触及全局工具的情况下升级项目工具链。

Yarn Berry 引入了深刻的架构变化，最显著的是即插即用和强大的插件系统。 默认情况下，Berry 更倾向于使用 PnP 而不是 node_modules支持零安装工作流程（依赖项已提交到存储库），并允许通过以下方式进行细粒度配置 .yarnrc.yml包括模块的连接方式、缓存的管理方式以及注册表和代理的定义方式。

Yarn 的维护者们强烈建议尽可能从 1.x 版本迁移到最新的 Berry 版本。 现代版本维护时间更长，修复了经典版本中存在的各种问题，并通过以下方式提供配置灵活性： nodeLinker 设置以便您仍然可以使用经典模式 node_modules 当 PnP 不适用时，可以使用布局或 pnpm 风格的符号链接。

如果您的生态系统或工具尚未准备好支持即插即用，您也无需担心。 只需设置 nodeLinker: node-modules in .yarnrc.ymlBerry 的行为更接近传统的 npm 安装，同时保留了其确定性的 lockfile、缓存行为和改进的 CLI 体验。

系统需求和全球纱线安装策略

无论你使用什么操作系统，Yarn 的真正硬性要求是必须安装 Node.js。 Yarn 是一个基于 Node 的命令行工具，它依赖于 Node 才能运行，因此您应该首先通过快速执行以下命令来确认 Node 是否可用。 node -v 在终端中，如果看到的是版本号而不是“命令未找到”错误，那就说明一切正常。

如果缺少 Node.js 或 Node.js 版本过旧，请使用适用于您平台的方法进行安装或升级。 在 Linux 系统上，您可以使用发行版软件包或 NodeSource 仓库；在 macOS 系统上，您可能更喜欢 Homebrew、MacPorts 或 nvm；而在 Windows 系统上，您可以使用官方安装程序或 Chocolatey 或 Scoop 等包管理器。许多 Yarn 工作流程都假定 Node 版本至少为 14.18，而对于 Berry 版本，Node 16 或 18 LTS 通常是最佳选择。

Yarn 的作者推荐采用两层安装模型。 首先，安装一个全局 yarn 只需在命令行界面 (CLI) 中运行一次（通常通过 npm），然后在每个项目中使用该全局命令来配置项目特定的 Yarn 版本，该版本直接存在于代码仓库中。这样可以确保所有贡献者和 CI 作业都执行项目定义的完全相同的 Yarn 版本。

通过 npm 安装全局 Yarn CLI 非常简单。 由于 npm 默认随 Node.js 一起发布，您可以运行：

sudo npm install -g yarn

安装完成后，验证全局 CLI 是否可访问。 跑：

yarn --version

如果你看到类似 1.22.x也就是说，全局经典启动器运行正常。 从现在开始，当你进入一个使用 Berry 的项目时，这个全局命令会将控制权透明地交给存储在存储库中的本地配置的 Yarn 版本。

在特定的 JavaScript 项目中安装 Yarn

全局 CLI 准备就绪后，下一步是将特定的 Yarn 版本“固定”到每个项目。 这正是确保团队成员的机器和 CI/CD 流水线保持一致性的关键：每个人都运行相同的 Yarn 二进制文件，因此行为也相同。

首先导航到您的项目目录（如果您要启动一个全新的应用程序，则创建一个新目录）。 例如：

mkdir my-project
cd my-project

在该文件夹内，使用特殊 yarn set version 命令用于选择最新的 Berry 版本。 一个典型的选择是追踪正在积极开发的“浆果”品系：

yarn set version berry

在后台，Yarn 将“berry”解析为最新的 Berry 二进制文件，下载它，并将其存储在一个文件中。 .yarn/releases 项目目录中。 同时，它创建或更新一个 .yarnrc.yml 项目根目录下的文件，用于告诉全局启动器将任务委托给该本地二进制文件。

如果你现在跑 yarn --version 再次从项目内部，输出将更改为项目固定的版本。 你可能会看到类似这样的内容 4.5.0 或者另一个 3.x/4.x 版本，表明您不再使用全局经典 CLI，而是使用托管在您的存储库中的本地 Berry CLI。

从现在开始，在该目录（或其子目录）中执行的每个 Yarn 命令都将使用项目特定的 Yarn 版本。 这样一来，团队就可以按照自己的节奏逐步将不同的项目迁移到更新的 Yarn 版本，同时在开发人员的机器上仍然安装一个全局启动器。

日常开发的核心 Yarn 命令

Yarn 安装并集成到您的项目中后，您只需要一小部分命令即可完成大多数日常任务。 CLI 功能非常强大，但只需几个子命令就能在管理依赖项和脚本方面取得很大进展。

当你感到困惑或想要探索更多选项时，每个命令都接受一个帮助标志。 运行：

yarn --help

打印通用帮助信息，同时追加 --help 在执行特定子命令后，会提供上下文使用提示。 例如， yarn install --help 解释依赖项安装过程中所有可用的标志。

要启动一个全新的项目，您可以让 Yarn 生成基本配置文件。 在一个空文件夹中，只需运行：

yarn init

该命令会引导您完成一些提示并写入一个 package.json 加上 yarn.lock 文件中。 前者声明了你的项目元数据、脚本和依赖项，而后者则作为 Yarn 在安装时解析的确切版本的权威记录。

加入一个已经使用 Yarn 的现有仓库时，通常的第一步是安装所有依赖项。 在项目根目录下，只需运行：

yarn install

Yarn 随后读取 package.json 和 yarn.lock下载缺失的所有内容，并建立依赖关系树。 由于缓存机制，即使在持续集成 (CI) 环境下，后续安装的速度也会比初始运行快得多。

添加新的依赖项同样简单明了 add 子命令。 例如，要安装 Express，您可以使用：

yarn add express

这条命令即可获取软件包并进行更新 package.json 并刷新 yarn.lock. 无需手动编辑 JSON 文件；Yarn 会自动为您保持声明的范围和锁定的版本同步。

快速检查：使用 Yarn 搭建小型 Express 服务器

如果您想确保 Yarn 完全按预期工作，可以使用 Express 编写一个简单的冒烟测试。 假设你身处一个项目中，并且已经运行过 yarn add express，创建一个名为 index.js 最低服务器配置如下：

const express = require("express");
const app = express();

app.get("/", (req, res) => res.send("Yarn is working!"));

app.listen(3000, () => console.log("Server running on http://localhost:3000"));

除了直接调用 Node 之外，您还可以通过 Yarn 运行此脚本，这在 PnP 环境中会很方便。 使用方法：

yarn node index.js

打开另一个终端，验证服务器是否响应正确。 简单来说：

curl http://localhost:3000

应该返回消息“Yarn 正在运行！”。 如果发生这种情况，说明 Yarn 已解决依赖关系，配置了模块解析，并顺利执行了脚本。

管理依赖项、脚本和 Yarn 缓存

除了安装和基本添加之外，Yarn 还提供了几个实用程序，可以干净利落地维护和发展您的依赖关系图。 这些命令避免了手动编辑并保留 package.json 和 yarn.lock 始终保持一致。

要移除不再需要的依赖项，请使用 remove 子命令。 例如：

yarn remove package-name

Yarn 将会卸载该软件包，并将其从系统中移除。 package.json并相应地更新锁定文件。 这样可以防止过时或未使用的模块残留在依赖树中。

依赖项的升级可以批量进行，也可以针对特定软件包进行升级。 没有争论，

yarn upgrade

根据您声明的范围解析兼容的更新版本，同时：

yarn upgrade package-name

针对单个依赖项。 在这两种情况下，Yarn 都会重写。 yarn.lock 为了反映更新后的依赖关系图。

当你的项目定义脚本时 package.json纱线 run 子命令是执行它们的方法。 类似这样的脚本：

"scripts": {
  "start": "node index.js"
}

可通过以下方式启动：

yarn run start

而且在许多情况下，较短的 yarn start 使用别名也可以。 无论底层模块链接策略如何，这都能在 Node 或其他工具之上提供一个清晰的抽象层。

Yarn 会保存所有先前下载的软件包的本地或全局缓存，以加快安装速度并提供离线功能。 有时，尤其是在进行实验或多次版本切换后，缓存可能会出现异常或损坏。如果您怀疑缓存存在问题，可以使用以下命令重置缓存：

yarn cache clean

如果您好奇 Yarn 将这些缓存的工件存储在哪里， yarn cache dir 打印位置信息。 当您需要在 Windows 防病毒软件中将缓存文件夹列入白名单，以避免因对每个下载的文件进行彻底扫描而导致安装速度变慢时，此功能尤其有用。

使用 .yarnrc.yml 配置 Yarn

Modern Yarn 将项目配置集中在一个位置 .yarnrc.yml 文件中。 此 YAML 文档控制依赖项的链接方式、缓存位置、PnP 的严格程度、注册表 URL、遥测等。

典型的配置可能如下所示：

nodeLinker: pnp
pnpMode: strict
compressionLevel: mixed
enableGlobalCache: true
enableTelemetry: false

此 nodeLinker 设置尤其重要，因为它定义了模块的解析方式。 有效选项包括 pnp （即插即用，无 node_modules 文件夹）， node-modules （经典布局），有时还会用到 pnpm 风格的链接器。如果您在使用硬编码工具时遇到兼容性问题。 node_modules 假设，切换到 node-modules 通常能解决这些问题。

compressionLevel 告诉 Yarn 应该以多大的强度压缩缓存包。 价值 0 完全禁用压缩以获得最高速度 1 强制进行完全压缩，以最大限度地减少磁盘占用，并且 mixed 它兼顾了这两个方面，这往往是大多数团队的明智之举。

启用 enableGlobalCache 使 Yarn 在多个项目中重用共享缓存目录。 这样，如果多个仓库依赖于相同的库，Yarn 就可以避免多次下载，从而节省网络带宽和磁盘空间。

最后， enableTelemetry 控制 Yarn 是否将匿名使用信息发送回维护者。 许多公司出于隐私和合规性原因选择关闭此功能，而另一些公司则选择开启此功能以帮助指导项目路线图；无论哪种方式，它都只是此配置文件中的一个标志。

Git 集成：哪些需要提交，哪些需要忽略

因为 Yarn 公司将其部分机器设备存放在…… .yarn 在目录下，对于哪些内容需要纳入版本控制，务必慎重考虑。 有些文件绝对应该被跟踪，而另一些则是缓存或构建产物，只会使存储库变得臃肿。

一个最小的 .gitignore Berry 在许多项目中采用的策略大致如下：

.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
.pnp.*

这种模式忽略了整个 .yarn 文件夹，但随后将需要提交的子目录列入白名单。 此 releases 例如，该目录包含项目特定的 Yarn 二进制文件；如果没有它，其他开发人员在克隆存储库时可能无法获得完全相同的 CLI 版本。

其他已列入白名单的路径，例如 .yarn/plugins or .yarn/sdks 支持自定义插件和编辑器集成。 对它们进行版本控制，可以确保团队中的每个人都共享相同的插件集和语言工具支持。

此 .pnp.* 条目是即插即用清单文件，用于描述使用 PnP 模式时的依赖关系树。 提交这些更改对于可复现的工作流程，有时甚至是零安装工作流程至关重要，因为 CI 或新的克隆可以立即运行项目，而无需重新生成清单。

此外，还要记住…… yarn.lock 是您代码库中的一等公民。 它必须始终与依赖项的更改一起提交和更新，否则 Yarn 的所有确定性优势都将消失。

Yarn vs npm：Yarn 真正大放异彩的时刻

Yarn 和 npm 解决的是同一个核心问题：管理 Node.js 依赖项，但 Yarn 在几个实际场景中脱颖而出。 最明显的区别通常体现在性能上：通过并行安装和更智能的缓存，Yarn 在大型项目中通常能更快地完成安装。

磁盘使用率是另一个优势，尤其是如果您采用即插即用模式的话。 通过消除 node_modules一个典型的项目可以占用更少的磁盘空间，并且与 PnP 集成良好的工具可以受益于更快的模块解析速度，因为 Node 不再需要遍历深而重复的目录树。

就锁定文件行为而言，Yarn 的 yarn.lock 因其结构紧凑、高度确定性而广受赞誉。 它会明确记录解决方案的决定，从而更容易理解为什么选择某个特定版本，并调试版本冲突。

单体仓库领域，Yarn 凭借其工作区功能一直处于领先地位。 借助工作区，单个存储库中的多个软件包可以共享一个锁定文件，依赖项可以高效地提升，本地软件包可以自动链接，而无需配置样板代码。

Yarn 在现实世界中的应用案例中表现出色，例如复杂的 CI/CD 设置、大型共享代码库或企业代理和自定义证书后面的环境。 例如，运行 yarn install --immutable CI 内部机制确保在以下情况下安装会失败： yarn.lock 文件不匹配 package.json它可以捕获不一致的依赖关系状态，防止它们进入生产环境。

另一方面，对于规模较小的项目或深度投入 npm 生态系统的团队来说，npm 仍然是一个完全有效的选择。 如果您只维护少数几个依赖关系树较小的服务，并且不大量依赖 monorepos 或 PnP，那么坚持使用 npm 的简单性可能比 Yarn 的高级功能更有优势。

操作系统特定安装选项

虽然基于 npm 的全局 CLI 安装几乎在任何地方都能运行，但 Yarn 也提供了特定于操作系统的发行版和脚本。 如果您更喜欢原生包管理器，或者您的系统没有方便的 npm 设置，那么这些工具就很有用。

在 macOS 系统上，非常流行的选择是通过 Homebrew 安装 Yarn。 假设您已经安装了 Node.js（也可能是通过 Homebrew 安装的），典型的流程如下：

brew install yarn

如果您使用 nvm 或其他 Node 版本管理器，请确保 shims 目录出现在 PATH 中任何 Homebrew Node 目录之前。 否则，运行 Yarn 脚本时，您最终可能会使用与预期不同的 Node 版本。

macOS 上还有另一种选择，那就是 MacPorts，它可以安装 Node.js 和 Yarn（如果尚未安装）。 为了实现更大的控制，Yarn 还发布了一个可在 macOS 和通用 Unix 上运行的安装 shell 脚本；将该脚本通过管道传输到您的 shell 中，即可一次性下载并安装 Yarn。

在 Windows 系统上，推荐的安装路径是 MSI 安装程序、Chocolatey 或 Scoop。 MSI 安装程序会引导您完成图形化安装向导，并且通常会在安装过程中确保 Node.js 已安装。而 Scoop 则允许您通过命令行安装 Yarn，如果缺少 Node.js，它还会选择性地建议安装。

在 Windows 上安装 Yarn 时，最好将项目文件夹和 Yarn 缓存目录（通常位于以下位置）都添加到白名单中。 %LocalAppData%\Yarn在你的杀毒软件里。 否则，每次文件下载和写入都可能需要扫描，这将大大降低安装速度。

Linux 发行版通常提供多种选择：官方系统软件包、Yarn 自己的存储库或手动 tarball 安装。 例如，在 Debian 和 Ubuntu 系统上，您可以添加 Yarn 的 APT 软件源，还可以选择配置 NodeSource 以获取最新版本的 Node.js，然后通过以下方式安装 Yarn： apt.

在 CentOS、Fedora、RHEL 或 Arch 等发行版上，Yarn 提供 GPG 签名的 tar 包，您可以下载并将其解压到磁盘上的任何位置。 在这些手动配置中，通常需要使用 GPG 验证 tar 包的签名，然后将解压后的 Yarn 目录添加到 PATH 环境变量中。 yarn 该命令可在系统范围内使用。

Unix、Linux 和 Windows 上的 PATH 配置

安装过程中常见的困惑来源是 PATH 配置：Yarn 可能已经安装，但 shell 找不到二进制文件。 在这种情况下，您必须更新您的环境，以便将 Yarn 目录包含在 PATH 变量中。

对于类 Unix 系统上的手动 tarball 安装，通常的做法是导出指向 Yarn 的路径。 bin 目录。 例如：

export PATH="$PATH:/opt/yarn-[version]/bin"

你需要将这行代码添加到你的 shell 配置文件中（例如： .bashrc, .bash_profile, .zshrc（或类似操作），然后打开一个新的终端会话或执行该文件，以使更改生效。 完成后 yarn --version 应该可以从任何目录运行。

如果你依靠 yarn global 命令方面，Yarn 还需要确保其全局 bin 文件夹位于 PATH 环境变量中。 实现此目的的快捷方法是扩展您的个人资料：

export PATH="$PATH:`yarn global bin`"

鱼壳使用者则依赖于 fish_user_paths 并且可以运行：

set -U fish_user_paths (yarn global bin) $fish_user_paths

在 Windows 系统上，您可能还需要手动将 Yarn 二进制目录添加到 PATH 环境变量中。 一个简单的例子是：

set PATH=%PATH%;C:\.yarn\bin

实际上，图形安装程序或 Windows 包管理器通常会为您处理 PATH 配置，但了解如何在出现问题时手动调整 PATH 仍然很有用。

常见安装问题及解决方法

即使有清晰的文档，团队在使用 Yarn 时仍然会反复出现某些安装问题。 幸运的是，他们中的大多数都有易于理解、可重复使用的解决方案。

反复出现的问题是，通过 npm 安装全局 CLI 时会出现与权限相关的错误。 如果你的 npm 前缀指向系统拥有的目录，则可以使用类似这样的命令：

sudo npm install -g yarn

或许可行，但从长远来看并非理想之选。 更好的做法是配置 npm 使用用户拥有的全局目录。您可以使用以下命令检查当前的目录前缀：

npm config get prefix

如果它指向以下某个东西 /usr创建您自己的目录并重新配置 npm。 例如：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

重新加载 shell 配置后，您应该能够全局安装 Yarn 而无需 sudo避免了许多权限审批方面的麻烦。

另一个常见的混淆来源是全局 Yarn 和项目 Yarn 之间的版本差异。 请记住，这是有意为之：全局 1.x CLI 只是一个启动器，当在 Berry 配置的项目中使用时，它会委托给项目中存在的任何版本。 .yarn/releases.

即使 Yarn 报告安装成功，但如果软件包似乎仍然缺失，则可能是因为您遇到了一个尚不理解 PnP 的工具。 一些编辑器、代码检查器或构建工具假定 node_modules 目录不存在时会失败。常见的解决方案包括启用 Yarn 的编辑器 SDK、使用 Yarn 支持矩阵中的兼容工具，或暂时将链接器切换到其他目录。 node-modules 通过 .yarnrc.yml.

在多个分支并行添加或更改依赖项的活跃团队中，锁定文件冲突是不可避免的。 日期 yarn.lock 如果在合并过程中发生冲突，一个有效的策略是选择一个分支作为基线，尽可能手动解决文本冲突，使之有利于该基线，然后运行合并。 yarn install 重新生成一个干净的锁定文件，并将其再次提交作为新的真理来源。

缓存相关问题通常可以通过简单的操作解决。 yarn cache clean 随后是新鲜的 yarn install. 如果 Yarn 运行异常，软件包看起来过时，或者出现奇怪的解析错误，清理缓存并重新安装通常可以使系统恢复正常状态，而无需进一步调查。

安装后检查和持续性能调优

Yarn 安装完毕并成功运行命令后，值得进行一些快速的健康检查，以确保项目中的所有连接都正确无误。 第一种方法也是最简单的方法是确认版本：

yarn --version

之后，在任何已经有……的项目中 package.json，执行 yarn install 没有错误提示有力地表明您的环境、注册表访问和 Node 版本是兼容的。 如果您的依赖项较多，您可能需要注意安装时间；在后续运行中，Yarn 的缓存和并发功能应该可以大大缩短安装时间。

Yarn 也提供了诸如此类的命令 yarn outdated 查看哪些软件包有更新版本可用，以及 yarn list --depth=0 打印所有实际安装的顶级依赖项。 这些工具可以帮助您跟踪依赖关系变化，并决定何时安排升级。

从性能方面来说，安装后您可以进行多种调整。 设置 networkConcurrency使用自定义缓存文件夹或在持续集成 (CI) 中禁用详细进度条，可以节省大型安装所需的几秒甚至几分钟。例如，增加并发性：

yarn config set network-concurrency 8

Yarn 可以并行发送更多网络请求，从而在高速连接上加快下载速度。

最后，对于非常大的单体仓库或多环境设置，将 Yarn 与可扩展的基础设施（例如基于容器的 CI 管道或云构建平台）相结合，可以充分利用其确定性和缓存友好的设计。 因为每次安装都受以下因素指导 yarn.lock 和 PnP 或 node_modules 元数据、CI 节点之间共享的缓存或在构建过程中重复使用的缓存可以显著缩短安装时间。

总而言之，花时间了解如何正确安装 Yarn、为每个项目固定 Yarn、调整 PATH 和配置，以及利用其缓存和工作区功能，很快就能获得回报。 最终，您将获得更快的安装速度、更可预测的构建、更好的单体仓库人体工程学，以及更容易在团队成员、CI/CD 系统和生产环境中重现的依赖项管理工作流程。