深入掌握 npm Workspaces：从零开始构建高效的 Monorepo 项目

2026-02-15 18:24:47 0条评论 2次阅读 0人点赞

作为一名开发者，你是否曾经在处理多个相互关联的项目时感到头疼？也许你有一个共享的工具库，被三个不同的应用程序引用；或者你正在维护一个庞大的系统，其中前端、后端和通用组件都分散在不同的仓库里。每当共享代码发生一点点变动，你就不得不在各个仓库之间同步版本，处理繁琐的依赖更新，甚至陷入“依赖地狱”。

这正是我们要探讨的问题。在本文中，我们将深入探讨 npm Workspaces 这一强大的原生工具。我们将一起学习如何利用它在一个单一的仓库中优雅地管理多个包，从而极大地简化我们的开发流程。我们将看到，通过 Workspaces，我们不仅可以轻松实现代码共享，还能统一管理依赖项，并显著提升项目的构建与安装速度。特别是在 2026 年这个由 AI 驱动的开发时代，一个结构清晰的 Monorepo 已经成为让 AI 辅助我们编写高质量代码的基石。

1 理解 npm Workspaces
2 使用 npm Workspaces 设置项目
3 创建工作区包
4 管理依赖项与安装逻辑
5 2026 开发范式：AI 辅助与 Monorepo 的结合
6 构建与跨工作区运行命令
7 发布包与供应链安全
8 最佳实践与注意事项
9 结语

理解 npm Workspaces

首先，让我们明确一下什么是 npm Workspaces 以及它为什么如此重要。

在此之前，你可能听说过像 Lerna 或 Yarn Workspaces 这样的工具。npm Workspaces 是从 npm v7.0.0 开始正式引入的一项原生功能，旨在解决“Monorepo”（单体仓库）架构下的依赖管理问题。简单来说，它允许我们在一个顶层目录下组织多个代码包，并将它们链接在一起。

核心优势是什么？

当我们初始化一个工作区环境后，npm 会做一件非常聪明的事情：符号链接。通常，如果我们在根目录安装依赖，npm 会将它们放在根目录的 INLINECODE499b86d4 中。而在 Workspaces 模式下，npm 会自动识别我们在配置文件中定义的子包，并将它们以符号链接的形式链接到根目录的 INLINECODE5d0e46b4 中。这意味着，你在 INLINECODE05b6bb12 中引用 INLINECODE0ba3d179 时，无需像发布到 npm 仓库那样下载安装，而是直接建立了一个实时的开发链接。修改 INLINECODE0ab76fef 的代码会立即反映在 INLINECODE6efc738e 中，无需重新安装。

使用 npm Workspaces 设置项目

让我们开始动手实践。为了充分利用这一功能，我们需要搭建一个坚实的基础。我们将创建一个典型的 Monorepo 结构，这在 2026 年的全栈开发中非常标准。

1. 初始化根目录

首先，创建一个新的项目目录。让我们把它叫做 INLINECODEe861142a。然后，我们需要初始化一个 INLINECODEb50656c5 文件。

# 创建项目根目录
mkdir my-monorepo-demo

# 进入目录
cd my-monorepo-demo

# 初始化 package.json
npm init -y

这一步会生成一个基础的 INLINECODE0b0371af。接下来，我们需要通过添加 INLINECODE221f0574 字段来告诉 npm：“嘿，请在这个目录下寻找并管理我的子包”。

2. 配置 Workspaces

打开根目录的 INLINECODE10ec7901 文件，添加 INLINECODE5f9735d7 字段。这个字段的值是一个数组，包含了通配符路径，告诉 npm 去哪里查找这些包。

{
  "name": "my-monorepo-demo",
  "version": "1.0.0",
  "private": true,
  "workspaces": [
    "packages/*"
  ],
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

配置详解：

"private": true: 这是一个关键设置。它防止我们意外地将根目录作为一个包发布到 npm 公共仓库上。对于 Monorepo 来说，根目录通常只是个容器，而不是一个独立的发布单元。
INLINECODE37bf07f8: 这里定义了工作区的位置。INLINECODE5b0cc1be 是通配符，意味着 INLINECODE1b5f554c 目录下的任何子目录都会被视为一个独立的工作区包。你也可以定义具体的路径，例如 INLINECODE0b42f265 或 "apps/*"，以区分后端服务和前端应用。

创建工作区包

配置好“容器”后，让我们来填充内容。我们将创建两个独立的包：一个核心工具库和一个使用该库的应用程序。

# 在根目录下创建 packages 子目录
mkdir packages

# 创建两个子包目录：utils（工具库）和 web-app（应用）
cd packages
mkdir utils web-app

现在，让我们为每个子包初始化它们自己的 package.json。

包 1: utils (共享工具库)

cd utils
npm init -y

编辑 packages/utils/package.json：

{
  "name": "@my-demo/utils",
  "version": "1.0.0",
  "main": "src/index.js",
  "type": "module", // 2026年的标准，使用 ESM
  "exports": { // 现代化的导出定义
    ".": "./src/index.js"
  },
  "scripts": {
    "test": "echo \"Testing utils package\" && exit 0"
  }
}

创建一个简单的 JS 文件 packages/utils/src/index.js：

/**
 * @file 简单的日期格式化工具
 * @description 这是一个跨包共享的工具函数
 */

// 箭头函数与简洁语法
export const formatDate = (date = new Date()) => {
  return date.toISOString();
};

// 添加一个计算函数用于展示更复杂的逻辑
export const add = (a, b) => a + b;

包 2: web-app (应用程序)

cd ../web-app
npm init -y

编辑 packages/web-app/package.json：

{
  "name": "@my-demo/web-app",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@my-demo/utils": "*" // 关键点：声明对本地包的依赖
  }
}

创建 packages/web-app/index.js：

// 尝试引用 utils 包
import { formatDate, add } from ‘@my-demo/utils‘;

console.log(‘当前时间:‘, formatDate());
console.log(‘计算结果 (1 + 1):‘, add(1, 1));

管理依赖项与安装逻辑

这是 Workspaces 最神奇的地方。让我们回到根目录，然后运行安装命令。

cd ../../ # 回到项目根目录
npm install

深入理解安装过程：

当我们运行这个命令时，npm 会执行以下操作：

读取配置：检测到根目录 INLINECODE68cad0e1 中的 INLINECODE49a20092 字段。
发现子包：扫描 INLINECODE2fd74cd1 和 INLINECODE802bb672。
处理内部依赖：INLINECODE3fcc2f92 的 INLINECODE7d698764 声明了 INLINECODEfc55fe6c。npm 会解析这个通配符，发现它指向本地的 INLINECODEd49369b9。然后，npm 会在 INLINECODEbb2f7281 创建一个指向 INLINECODE2ad7c49a 的符号链接。
提升公共依赖：这是性能优化的关键。如果 INLINECODE66b2d80e 需要 INLINECODEe5cc7ee3，INLINECODEdf5561a4 也需要 INLINECODE1967eab7，npm 会将依赖安装到根目录的 INLINECODE1e32bf11 中。这种“去重”机制不仅节省了磁盘空间（这在动辄数 GB 的 INLINECODEc0988a24 时代尤为重要），还加速了 CI/CD 流程中的依赖安装步骤。

让我们添加一个外部依赖来演示一下。假设我们想给 INLINECODEf963df8b 包安装 INLINECODE86abdf7e：

# 使用 -w (或 --workspace) 参数指定包
npm install axios -w @my-demo/web-app

2026 开发范式：AI 辅助与 Monorepo 的结合

在 2026 年，代码库的结构直接决定了 AI 辅助编程的效率。为什么？因为像 Cursor 或 GitHub Copilot 这样的 AI 工具，在处理结构清晰的 Monorepo 时表现更出色。我们将这种现象称为 "Context Awareness"（上下文感知）。

为什么 Monorepo 是 AI 的最佳搭档？

当我们将所有代码放在一个仓库中，并通过 npm Workspaces 明确定义了包之间的边界时，我们就给了 AI 一个“上帝视角”。

精准的代码补全：在 INLINECODEa3af2964 中编写代码时，如果 AI 拥有仓库权限，它能“看到” INLINECODEc6992226 包的实现细节。这意味当你调用一个内部函数时，AI 不仅仅是在猜测参数类型，它是根据实际的源代码来提供建议的。
自动化重构：假设我们决定修改 INLINECODEf9a00069 包中 INLINECODE7f4ab567 函数的签名。在分散的仓库中，你需要手动更新每一个下游项目，或者让 AI 在每个项目中分别尝试修改。而在 Monorepo 中，AI 可以一次性扫描所有引用了该函数的工作区，并原子化地提交所有修改。

实战：利用 AI 帮我们编写测试

让我们来看一个实际场景。我们刚刚写好了 utils 包，现在想为它编写测试。在传统的开发流程中，你需要手动写断言。而在 2026 年的 Vibe Coding（氛围编程） 理念下，我们可以这样操作：

确保你的 IDE（如 Cursor 或 Windsurf）开启了“全仓库索引”模式。
在 INLINECODEb14e5693 目录下创建一个空的 INLINECODE5a33d6d7。
输入提示词：“为 INLINECODE445cafe5 中的 INLINECODE9ccfb56c 函数编写完整的单元测试，覆盖边界情况”。

由于 Workspaces 让路径变得透明，AI 会立刻理解依赖关系，并生成如下代码：

import { add } from ‘../src/index.js‘;
import { expect } from ‘chai‘; // 假设我们已经安装了 chai

// AI 生成的测试代码
describe(‘add function‘, () => {
  it(‘should correctly add two positive numbers‘, () => {
    expect(add(1, 2)).to.equal(3);
  });

  it(‘should handle zero correctly‘, () => {
    expect(add(5, 0)).to.equal(5);
  });

  // AI 甚至会考虑到类型转换等边界情况
  it(‘should handle string coercion if applicable‘, () => {
    // 基于代码分析的断言
  });
});

技术洞察：npm Workspaces 不仅是文件系统的组织方式，它是将代码库转化为知识图谱的基础设施。只有当依赖关系明确且实时链接，AI 才能充当我们的结对编程伙伴，而不仅仅是自动补全工具。

构建与跨工作区运行命令

随着项目变大，一个一个地进入子目录去运行测试或构建脚本是非常低效的。我们可以利用 npm Workspaces 的工作区过滤功能来批量执行命令。这对于微服务架构的本地开发尤为关键。

1. 并行执行

假设我们在每个子包的 INLINECODE7a39d213 中都定义了一个 INLINECODE1d35daae 脚本：

// packages/utils/package.json 和 packages/web-app/package.json 中都添加
"scripts": {
  "lint": "eslint ."
}

现在，让我们在根目录运行：

# 使用 --workspaces 标志在所有包中并行运行脚本
npm run lint --workspaces

这将并行地在 INLINECODE4ada1aeb 和 INLINECODE47d591d2 中执行 INLINECODEe67f4923 命令。npm 并没有内置的任务运行器来严格管理并发数，但在 2026 年，我们通常会结合 INLINECODE3d970ed8 或 turborepo 等工具来接管这一层。不过，原生的 npm Workspaces 足以应付中小型项目的并行构建需求。

2. 针对性运行

如果我们只想运行 INLINECODEbc1fe4fe 包的启动脚本呢？使用 INLINECODEdc4918ac 标志：

# 仅在 web-app 包中运行 start 脚本
npm run start -w @my-demo/web-app

3. 建立根脚本别名

为了进一步简化团队协作，建议在根目录 package.json 中添加聚合脚本：

{
  "scripts": {
    "dev": "npm run start -w @my-demo/web-app",
    "test:all": "npm test --workspaces",
    "clean": "npm run clean --workspaces"
  }
}

现在，新加入的开发者只需要在根目录运行 npm run dev，就能轻松启动整个开发环境。

发布包与供应链安全

开发完成后，我们可能需要将 utils 发布到 npm 供其他人使用，或者仅仅是为了部署。

现代化发布实践

在 2026 年，我们不仅要发布代码，还要确保供应链的安全。在发布之前，请务必确保你的 INLINECODEf6d9b0c0 配置正确。特别是使用了 scope（如 INLINECODEa976cfe5）时。

让我们尝试发布 utils 包：

# 发布特定的 workspace 包
# 注意：npm v9+ 开始默认强制使用 provenance 声明
npm publish --workspace=@my-demo/utils --access public

关于 Provenance（来源声明）：

从 2026 年的视角来看，仅仅发布代码是不够的。npm 现在强烈推荐使用 --provenance 标志。这会在你的包中嵌入一个 OIDC 签名，证明这个包确实是由你在 CI/CD 流程中发布的，而不是被黑客注入的。

如果你的 CI 环境配置正确（如 GitHub Actions），npm 会自动检测到 OIDC token 并签名你的包。

最佳实践与注意事项

虽然 Workspaces 很强大，但我们在使用时仍需保持一定的纪律性，以避免项目变成“大泥球”。

1. 严格的包边界

尽量保持各个子包之间的解耦。这被称为 “垂直切片”。如果 INLINECODEfb0a422f 包直接依赖了 INLINECODEafe6da87 的内部文件夹（例如 INLINECODE1ced49da），这会破坏封装性。始终通过 INLINECODEa51f529d 的 INLINECODE2e6eb7d0 或 INLINECODEe27dee64 字段来暴露接口。

2. 版本管理策略

在 Monorepo 中管理版本号是一个复杂的话题。虽然 npm Workspaces 负责链接，但它不负责版本发布。建议配合 Changesets 这样的工具。Changesets 允许你为每次变更加上一个 INLINECODE4a389e19 文件，描述这次改动是 INLINECODEeee17267、INLINECODE84494fa4 还是 INLINECODEc11a6314。然后，它会自动帮你升级所有相关包的版本号，并生成 CHANGELOG。

3. 避免“幽灵依赖”

这是一个经典的陷阱。如果 INLINECODE03e38de7 依赖 INLINECODE2cab8f2d，而 INLINECODEa42474fa 没有声明依赖 INLINECODE153254f9，但在代码中却使用了 INLINECODE4c9faf71。在 Workspaces 模式下，由于依赖提升，这通常是可行的（因为 lodash 在根 nodemodules 中）。然而，一旦你单独发布 INLINECODE89c04852 到生产环境，它就会崩溃，因为它的 INLINECODEe96f2bfa 里没有写 INLINECODEae58d713。务必确保每个包的 INLINECODE72c47f9a 声明了它直接使用的所有依赖。

结语

通过这篇文章，我们一起探索了 npm Workspaces 的方方面面，并展望了它在 2026 年技术栈中的位置。从基础的初始化、依赖提升原理，到它如何成为 AI 辅助编程的强大后盾，我们看到了它是如何将分散的项目整合成一个高效、统一的开发环境。

npm Workspaces 不仅解决了依赖地狱的问题，更为构建大型、可持续演进的应用铺平了道路。它让我们无需引入复杂的第三方工具，就能享受到代码共享、统一构建和原子化提交带来的便利。当你下次准备搭建一个新的全栈项目时，不妨试着把 Workspaces 作为你的基础设施。你会发现，管理多包项目其实可以很简单，甚至有点“优雅”。

现在，去尝试创建你自己的 Monorepo 吧，把那些纠缠不清的项目整理得井井有条，并让 AI 帮你写出更好的代码！

投稿给我们	如何建站？
vps是什么？	如何安装宝塔？
如何通过博客赚钱？	便宜wordpress托管方案
免费wordpress主题	这些都是免费方案

豆丁博客