在一篇文章中掌握使用 npm、yarn 和 pnpm 的工作区！

workspaces（工作区）是一个通用术语，它指的是从单个*根包中管理本地文件系统中的多个包。

npm、yarn、pnpm都提供了对workspaces的支持，在使用上会有些微的不同，今天就分享一下这几个包管理器分别使用workspaces的方式

前段时间写几个独立的组件，当时因为没考虑要做成啥样，就把demo文档和组件放在一个包管理了，随着需求的增多，不得不把文档抽离出来，由于前期都是用的npm（因为要使用新发布的包），就直接使用npm的workspaces了

npm的workspaces介绍及使用

npm官网的介绍

以一个简单的组件库demo为例

项目初始化

创建vangle目录为项目的根目录，初始化package.json

cd vangle
npm init -y

package.json

{
  "name": "vangle",
  "version": "1.0.0",
  "license": "ISC"
}

手动添加子包

创建packages存放所有的子包，然后在该目录下新建docs和components目录，分别初始化子包的package.json

packages/components/package.json

{
  "name": "components",
  "version": "1.0.0",
  "license": "ISC"
}

packages/docs/package.json

{
  "name": "docs",
  "version": "1.0.0",
  "license": "ISC"
}

• 目录结构为

|-- vangle
    |-- package.json
    |-- packages
        |-- components
        |   |-- package.json
        |-- docs
            |-- package.json

在根项目的package.json中添加workspaces，其实就是包的路径数组，支持Glob通配符，这里的路径指向指的是package.json所在文件夹文件夹名。

{
  "name": "vangle",
  "version": "1.0.0",
  "license": "ISC",
  "workspaces": [
    "packages/components",
    "packages/docs"
  ]
}

这时执行npm install后node_modules下就会有components和docs的依赖了

上面是手动添加子包的方式，npm也提供了命令行的方式添加，所做的功能和上面手动类似，-w 就是 --workspace 的简写，但用法稍有区别，如下：

npm init -w ./packages/a -y
# or
npm init --workspace=./packages/b -y

没有层级目录会自动创建，生成pckage.json并在根目录package.json中添加workspace路径

• workspaces也支持glob通配符，例如像下面这样配置表示匹配packages目录下所有的一级子包

{
  "workspaces": [
    "packages/*"
  ]
}

为子包添加、移除、更新依赖

• 如果想为components包添加dayjs依赖，可以使用一下命令操作，使用-w [packageName]来告诉npm为哪个子包添加依赖

npm install dayjs -w components
npm uninstall dayjs -w components
npm update dayjs -w components

# or
npm install dayjs --workspace=components

注意：如果在项目根目录运行 npm install 会同时将子包及子包的依赖一起安装到根node_modules下

使用子包

为components、docs分别添加如下代码，由于docs依赖components建议位docs包添加依赖

npm install components -w docs

// packages/components/index.js
export const button = 'button'

// packages/docs/index.js
import { button } from 'components'
console.log(button)

在docs/package.json中添加启动脚本

{
  "name": "docs",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "license": "ISC",
  "scripts": {
    "dev": "node index.js"
  }
}

因为使用了ES module 需要添加"type": "module"，在docs/index.js中导入了components，默认回去加载components/index.js，建议加上"main": "index.js"，不然会有提示

• 运行启动命令 dev

npm run dev -w docs
# run many
npm run dev -w docs -w components

# or
npm run dev --workspace=docs
npm run test --workspace=docs --workspace=components

• 如果我们想启动子包的所有dev脚本可以使用--workspaces参数，如果有的子包没有dev脚本会报错，使用 --if-present参数可以避免

npm run dev --workspaces

# 有就运行
npm run dev --workspaces --if-present

在根package.json中运行工作区脚本

和上面一模一样，好处是可以简写运行的命令

"scripts": {
  "dev": "npm run dev --workspaces",
  "docs:dev": "npm run dev -w docs"
}

上面就是npm工作区的基本使用，这里快速总结一下几个常用命令

# 新增子包
npm init -w ./packages/a -y

# 为子包添加依赖
npm install dayjs -w components

# 运行子包的dev脚本
npm run dev -w docs

# 运行所有子包dev脚本，注意 --if-present 的使用时机
npm run dev --workspaces

yarn 使用 workspaces

yarn官网的介绍

其实和npm差不多，这里还是按上面的方式操作一遍

工作区是一种设置包架构的新方法，从 Yarn 1.0 开始默认可用。 它允许你设置多个包，这样你只需要运行 yarn install 就可以一次性安装所有包。

使用npm安装yarn

npm install -g yarn

项目初始化

创建vangle目录为项目的根目录，初始化package.json

cd vangle
yarn init -y

package.json

{
  "name": "vangle",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "private": true,
  "workspace": [
    "packages/docs",
    "packages/components"
  ]
}

private：根目录一般是项目的脚手架，无需发布，"private": true会确保根目录不被发布出去

workspaces：其实就是包的路径数组，支持Glob通配符，这里的路径指向指的是package.json所在文件夹文件夹名。

相关命令

显示你当前项目的工作空间依赖树

yarn workspaces info

{
  "docs": {
    "location": "packages/docs",
    "workspaceDependencies": [],
    "mismatchedWorkspaceDependencies": []
  },
  "components": {
    "location": "packages/components",   
    "workspaceDependencies": [],
    "mismatchedWorkspaceDependencies": []
  }
}

选定的工作空间（即包）中运行所选的yarn命令 yarn workspace <package-name> <command>

# 添加依赖
yarn workspace docs add dayjs

# 移除依赖
yarn workspace docs remove dayjs

如果你想为所有的包添加一个共同的依赖关系，进入项目的根目录并使用-W (或-ignore-workspace-root-check) 标志

yarn add dayjs -W -D

在docs包中安装components包（安装本地包），运行下面的命令，必须加上版本号

yarn workspace docs add components@1.0.0

# or
cd .\packages\docs
yarn add components@1.0.0

注意：如果远程仓库有相同名称相同版本的包会优先下载远程的，注意命名

hoist 依赖提升问题

如果我们直接切换到子包如：cd .\packages\docs，然后添加依赖 yarn add -D typescript，这时依赖还是会添加到根级的node_modules里

这是因为yarn默认会把子包安装的依赖会提升到根级，如果你想在子包中安装它，需要在根package.json中设置不需要提升的包nohoist，注意workspaces的结构

{
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": ["**/docs", "**/docs/**"]
  }
}

npm 原始好像没有nohoist的实现，所以上面没讲 github.com/npm/rfcs/is…

运行工作区npm脚本

• 运行docs的dev脚本

yarn workspace docs dev

• 在根package.json中运行工作区脚本 yarn docs:dev

"scripts": {
  "docs:dev": "yarn workspace docs dev"
}

pnpm 使用 workspaces

pnpm官网的介绍

相比于npm和yarn，pnpm就是专门为menorepo而生的，提供了一些高级的workspaces用法。一些知名的开源项目如：Next.js、Vue3.0、Vite、Nuxt等都陆续使用pnpm作为脚手架。

使用pnpm有以下几个优势，这也是pnpm项目的初衷。

• 节省磁盘空间
• 提高安装速度
• 创建一个非扁平的 node_modules 目录

使用npm安装pnpm

npm install -g pnpm

pnpm和npm、yarn的用法相似，这里就不作过多介绍了，主要讲讲与workspaces相关的内容

项目初始化

创建vangle目录为项目的根目录，初始化package.json

mkdir vangle
cd vangle
pnpm init -y

pnpm 内置了对单一存储库（也称为多包存储库、多项目存储库或单体存储库）的支持， 你可以创建一个 workspace 以将多个项目合并到一个仓库中。

与npm、yarn不同，pnpm的workspaces的配置都放在pnpm-workspace.yaml文件里

一个 workspace 的根目录下必须有 pnpm-workspace.yaml 文件， 也可能会有 .npmrc 文件。

pnpm-workspace.yaml 定义了 工作空间 的根目录，并能够使您从工作空间中包含 / 排除目录 。 默认情况下，包含所有子目录。

# pnpm-workspace.yaml
packages:
  # all packages in direct subdirs of packages/
  - 'packages/*'
  # # all packages in subdirs of components/
  # - 'components/**'
  # # exclude packages that are inside test directories
  # - '!**/test/**'

初始化子包命令

和 npm 类似

pnpm init -w ./packages/docs -y
pnpm init -w ./packages/components -y

• 在项目根目录安装依赖

# 使用 --ignore-workspace-root-check 或 -w 来标记，否则在 root workspace 包添加依赖项时会失败。
pnpm add dayjs -w

• 为子包添加依赖，--filter 或 -F 的使用，--filter 后面跟的是包名

pnpm add dayjs --filter docs

• 安装工作区里的子包，例如docs安装components作为依赖

pnpm add components --filter docs

我们看看docs/package.json中写入的是什么"components": "workspace:^1.0.0"，前面有workspace:说明这个依赖来自于本地工作区

{
  "dependencies": {
    "components": "workspace:^1.0.0",
    "dayjs": "^1.11.7"
  }
}

workspace:是pnpm Workspace的协议，这里是官网的详细解释

默认情况下，如果可用的 packages 与已声明的可用范围相匹配，pnpm 将从工作区链接这些 packages。 例如, 如果bar引用"foo": "^1.0.0"并且foo@1.0.0存在工作区，那么pnpm会从工作区将foo@1.0.0链接到bar。 但是，如果 bar 的依赖项中有 "foo": "2.0.0"，而 foo@2.0.0 在工作空间中并不存在，则将从 npm registry 安装 foo@2.0.0 。 这种行为带来了一些不确定性。

幸运的是，pnpm 支持 workspace 协议 workspace: 。 当使用此协议时，pnpm 将拒绝解析除本地 workspace 包含的 package 之外的任何内容。 因此，如果您设置为 "foo": "workspace:2.0.0" 时，安装将会失败，因为 "foo@2.0.0" 不存在于此 workspace 中。

当 link-workspace-packages 选项被设置为 false 时，这个协议将特别有用。 在这种情况下，仅当使用 workspace: 协议声明依赖，pnpm 才会从此 workspace 链接所需的包。

详细内容请参考 pnpm.io/zh/workspac…

hoist相关配置

pnpm 提升方式，我们可以在 .npmrc 对其进行配置，.npmrc 文件都遵循 INI-formatted 列表，包含 key = value 参数。

更详细的配置请参考 pnpm.io/zh/npmrc

hoist

• 默认值： true
• 类型： boolean

当 hoist 为 true 时，所有依赖项都会被提升到 node_modules/.pnpm/node_modules。 这使得 node_modules所有包都可以访问 未列出的依赖项。

hoist = true

hoist-pattern

• 默认值： ['*']
• 类型： string[]

告诉 pnpm 哪些包应该被提升到 node_modules/.pnpm/node_modules。 默认情况下，所有包都被提升 —— 但是，如果您知道只有某些有缺陷的包具有幻影依赖，您可以使用此选项专门提升幻影依赖（推荐做法）。

例如：

hoist-pattern[]=*eslint*
hoist-pattern[]=*babel*

还可以使用排除模式，过滤不需要提升的依赖

例如：

hoist-pattern[]=*types*
hoist-pattern[]=!@types/react

shamefully-hoist

• 默认值： false
• 类型：Boolean

默认情况下，pnpm 创建一个半严格的 node_modules，这意味着依赖项可以访问未声明的依赖项，但 node_modules 之外的模块不行。 通过这种布局，生态系统中的大多数的包都可以正常工作。 但是，如果某些工具仅在提升的依赖项位于根目录的 node_modules 时才有效，您可以将其设置为 true 来为您提升它们。

shamefully-hoist = true

运行工作区npm脚本

• 运行docs的dev脚本

pnpm --filter docs dev

• 在根package.json中运行工作区脚本 pnpm docs:dev

"scripts": {
  "docs:dev": "pnpm --filter docs dev"
}

最后

本文介绍了在npm、yarn、pnpm中使用workspaces的方式，基本功能都有实现，但pnpm确实提供了npm和yarn所没有的功能，可以根据项目的需要具体选择使用哪个