Yarn 使用指南

發表於 分類於

Yarn 使用指南

什麼是 Yarn？

Yarn 是一個快速、可靠且安全的 JavaScript 套件管理工具，由 Facebook、Google、Exponent 和 Tilde 共同開發，用於管理 Node.js 專案中的依賴套件。

主要特點

  • 快速：並行化操作，提升安裝速度
  • 可靠：使用詳細的鎖定檔案（lockfile）確保跨裝置的一致性
  • 安全：使用校驗和驗證每個已安裝套件的完整性
  • 離線模式：已快取的套件可在離線狀態下重新安裝
  • 工作區（Workspaces）：原生支援 monorepo 專案管理

環境需求檢查

在安裝 Yarn 之前，請確認您的環境已安裝 Node.js：

1
2
node -v && npm -v
# 範例輸出：v18.20.8 / 10.8.2

如果出現版本號，表示環境已準備就緒。

Yarn 安裝方式

方法一：使用 Corepack（推薦）

Corepack 是 Node.js 內建的套件管理器管理工具，可以為每個專案指定不同的 Yarn 版本，是目前官方推薦的安裝方式。

步驟 1：啟用 Corepack

1
corepack enable

步驟 2：驗證安裝

1
yarn exec env | grep COREPACK_ROOT

如果看到 COREPACK_ROOT 相關輸出，表示 Corepack 已成功啟用。

步驟 3：設定專案的 Yarn 版本

1
2
3
4
5
# 使用最新穩定版
yarn set version stable

# 或指定特定版本（如 Yarn 1.x Classic）
corepack prepare yarn@1.22.22 --activate

方法二：全域安裝（不推薦）

⚠️ 注意：此方法已不再是官方推薦的安裝方式，因為全域版本可能導致不同專案間的版本衝突。

1
npm install -g yarn

Yarn 版本說明

Yarn 目前有兩個主要版本系列：

版本系列 別名 特色 適用場景
Yarn 1.x Yarn Classic 穩定、相容性高 傳統專案、與 npm 高度相容的環境
Yarn 2+ Yarn Berry 現代化、PnP 模式、插件系統 新專案、monorepo、追求效能優化

查看當前版本

1
yarn --version

專案級版本管理

使用 Corepack 可以為不同專案鎖定不同的 Yarn 版本，避免版本衝突。

範例：多專案版本管理

專案 A（使用 Yarn 1.x Classic）

1
2
cd /path/to/project-a
corepack prepare yarn@1.22.22 --activate

專案 B（使用 Yarn 4.x Modern）

1
2
3
4
cd /path/to/project-b
corepack prepare yarn@stable --activate
yarn set version stable
yarn install

在 package.json 中鎖定版本

1
2
3
{
  "packageManager": "yarn@3.1.0"
}

當其他開發者執行 yarn 時，Corepack 會自動使用指定的版本。

常見錯誤處理

錯誤：yarn : The term 'yarn' is not recognized...

原因：系統未安裝 Yarn 或未正確設定 PATH。

解決方法：

1
2
3
4
5
# 方法 1：啟用 Corepack（推薦）
corepack enable

# 方法 2：全域安裝（不推薦）
npm install -g yarn

常用指令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 初始化新專案
yarn init
yarn init -2  # 使用 Yarn Berry 初始化

# 安裝依賴
yarn install
yarn  # 簡寫

# 新增套件
yarn add <package-name>
yarn add <package-name>@<version>
yarn add -D <package-name>  # 開發依賴
yarn add -i <package-name>  # 互動式選擇版本

# 更新套件
yarn up <package-name>

# 移除套件
yarn remove <package-name>

# 執行腳本
yarn run <script-name>
yarn <script-name>  # 簡寫

# 查看套件資訊
yarn npm info <package-name>
yarn npm info <package-name>@next  # 查看特定標籤版本

# 版本管理
yarn set version stable
yarn set version from sources  # 從原始碼安裝
yarn set version from sources --branch 1211  # 從特定分支安裝

進階功能

工作區（Workspaces）

適用於 monorepo 專案管理：

1
2
3
4
5
{
  "workspaces": [
    "packages/*"
  ]
}
1
2
3
4
5
# 為所有工作區更新套件
yarn up <package-name>

# 新增工作區依賴
yarn add lib@workspace:^

Patch Protocol

當需要修補第三方套件時：

1
yarn add @types/react@patch:@types/react@18.0.0#./my-patches/react-types.patch

或在 package.json 中：

1
2
3
4
5
{
  "dependencies": {
    "left-pad": "patch:left-pad@1.3.0#./my-patch.patch"
  }
}

版本發布工作流程

1
2
3
4
5
# 檢查哪些套件需要發布
yarn version check

# 互動式檢查版本
yarn version check --interactive

與 Volta 整合

如果您使用 Volta 管理 Node.js 版本，需要特別處理 Corepack 整合：

1
2
3
4
npm install -g corepack

# 明確指定安裝目錄以覆蓋 Volta 的 shims
corepack enable --install-directory ~/.volta/bin

參考資源