Monorepo 架构全解析：从概念到落地实践

三、技术栈选择

在众多 Monorepo 解决方案中，本次选用的技术栈及核心理由如下：

四、项目目录结构设计

合理的目录结构是 Monorepo 成功的关键，本次采用经典的分层结构，清晰区分业务应用与公共资源，具体结构如下：

LowCode/
├── package.json # 根项目配置（管理公共依赖、脚本命令）
├── tsconfig.base.json # TypeScript 基础配置（共享给所有子项目）
├── .yarn/ # Yarn 配置
├── .yarnrc.yml # Yarn 运行时配置
├── 其他配置...
├── apps/ # 业务项目目录（独立部署的应用）
│   ├── web/ # 前端 Web 应用
│   │   └── package.json
│   ├── api/ # 后端 API 服务
│   │   └── package.json
└── packages/ # 公共包目录（可被其他项目依赖）
    ├── utils/ # 工具函数库
    │   └── package.json
    ├── components/ # UI 组件库
    │   └── package.json
    └── config/ # 共享配置库
        └── package.json

核心目录说明：

• apps/ ：存放业务应用，每个应用都是独立可部署的项目，如前端 Web 应用和后端 API 服务；
• packages/ ：存放可重用的公共库，供 apps 目录下的项目依赖使用，包括工具函数、UI 组件和共享配置等；
• 根目录：承担全局管理职责，包含项目级公共配置、共享脚本、依赖声明和项目文档。

五、实现步骤详解

Monorepo 的实现遵循'初始化 - 配置 - 细化'的流程，从根项目搭建到子项目配置逐步推进，确保每个环节衔接顺畅。

1. 初始化根项目

首先创建项目根目录并通过 Yarn 初始化，生成基础的 package.json 文件：

mkdir LowCode
cd LowCode
yarn init -y

2. 配置 Yarn Workspace

Yarn Workspace 是实现 Monorepo 依赖管理和项目关联的核心，需在根项目的 package.json 中添加如下配置，明确工作空间范围和公共脚本：

{
  "name": "low_code",
  "version": "1.0.0",
  "packageManager": "[email protected]",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "test": "yarn workspaces foreach -A run test",
    "build:all": "yarn workspaces foreach -A -p run build",
    "build:apps": "yarn workspaces foreach -A --include 'apps/*' -p run build",
    "build:packages": "yarn workspaces foreach -A --include 'packages/*' -p run build",
    "dev:web": "yarn workspace @wect/web dev",
    "dev:api": "yarn workspace @wect/api dev",
    "dev:all": "concurrently \"yarn workspace @wect/web dev\" \"yarn workspace @wect/api dev\"",
    "clean": "yarn workspaces foreach -A -p run clean",
    "add": "yarn workspace",
    "remove": "yarn workspace",
    "lint": "yarn workspaces foreach -A -p run lint",
    "lint:fix": "yarn workspaces foreach -A -p run lint:fix",
    "format": "prettier --write './**/*.{js,jsx,ts,tsx,json,md,yml}' --ignore-path .prettierignore",
    "format:check": "prettier --check './**/*.{js,jsx,ts,tsx,json,md,yml}' --ignore-path .prettierignore"
  },
  "devDependencies": {
    "concurrently": "^9.2.1"
  }
}

配置关键点：

• private: true 确保根项目不会被意外发布；
• workspaces 数组定义工作空间位置，自动识别指定目录下的子项目；
• 通过 workspace 命令操作单个子项目，workspaces foreach 批量操作所有子项目；
• 子项目名称统一使用作用域前缀（如 @wect/web），避免命名冲突。

3. 配置 Yarn 运行时

创建 .yarnrc.yml 文件，指定 Yarn 的依赖链接模式，本次采用经典的 node-modules 模式，兼容性更强：

# Yarn 配置文件
nodeLinker: node-modules

4. 初始化子项目

子项目初始化提供两种方式，可根据实际需求选择：

方法一：批量初始化（推荐）

先安装任务调度依赖 concurrently，再通过 Yarn 命令批量初始化所有子项目：

# 安装公共开发依赖
yarn add -D concurrently
# 批量初始化所有子项目
yarn workspaces foreach -A -p init

方法二：手动初始化（适用于个别项目）

进入具体子项目目录，单独执行初始化命令，以 web 应用为例：

cd apps/web
yarn init -y

5. 配置子项目

每个子项目需配置独立的 package.json，明确自身依赖、脚本命令等信息，同时通过 workspace 协议关联内部公共包。以下是核心子项目的配置示例：

Web 应用配置（apps/web/package.json）

{
  "name": "@wect/web",
  "version": "1.0.0",
  "private": true,
  "packageManager": "[email protected]",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "echo '运行 Web 测试...'",
    "clean": "rm -rf dist",
    "lint": "eslint 'src/**/*.{js,jsx,ts,tsx}'",
    "lint:fix": "eslint 'src/**/*.{js,jsx,ts,tsx}' --fix",
    "format": "prettier --write 'src/**/*' --ignore-path ../../.prettierignore"
  },
  "dependencies": {
    "@wect/utils": "workspace:*",
    "@wect/components": "workspace:*",
    "@wect/config": "workspace:*",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.14.10",
    "@types/react": "^19.2.0",
    "@types/react-dom": "^19.2.0",
    "@vitejs/plugin-react": "^5.2.0",
    "eslint": "^9.7.0",
    "eslint-plugin-react": "^7.35.0",
    "eslint-plugin-react-hooks": "^4.6.2",
    "typescript": "^5.5.3",
    "vite": "^6.3.9"
  }
}

API 服务配置（apps/api/package.json）

{
  "name": "@wect/api",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "echo \"启动 API 开发服务器...\"",
    "build": "echo \"构建 API 服务...\"",
    "test": "echo \"运行 API 服务测试...\"",
    "lint": "echo \"检查 API 服务代码...\"",
    "clean": "echo \"清理 API 服务构建产物...\"",
    "deploy": "echo \"部署 API 服务...\""
  },
  "dependencies": {
    "@wect/utils": "workspace:*",
    "@wect/config": "workspace:*"
  }
}

6. 依赖管理详解

Monorepo 中的依赖管理分为'外部依赖'和'内部依赖'，需采用不同的管理方式：

安装外部依赖

根据依赖的作用范围，可安装在根项目（所有子项目共享）或特定子项目：

# 安装根项目依赖（所有子项目共享）
yarn add -D prettier eslint
# 为 web 应用单独安装依赖
yarn workspace @wect/web add react react-dom

依赖内部子项目

使用 workspace: 协议引用其他工作空间，确保始终使用本地最新版本，避免版本不一致问题：

{
  "dependencies": {
    "@wect/utils": "workspace:*",
    "@wect/components": "workspace:*"
  }
}

7. 常用脚本命令详解

根项目的 scripts 配置了批量操作子项目的命令，结合 Yarn Workspace 特性实现高效管理，核心命令及用途如下：

批量命令技巧：

• -A 参数：操作所有工作空间；
• -p 参数：并行执行命令，提升效率；
• --include 参数：过滤目标工作空间，如 --include 'apps/*' 仅操作应用项目。

六、版本一致性保障

Monorepo 中依赖版本不一致是常见问题，可能导致运行报错或功能异常，需从以下三方面保障版本统一：

1. 根级依赖锁定：将 TypeScript、构建工具、代码规范工具等公共依赖在根项目的 package.json 中明确定义版本，子项目无需重复声明，直接继承根依赖版本；
2. 使用 workspace 协议：子项目间的依赖必须使用 workspace:* 协议，确保始终引用本地最新版本，避免子项目间依赖版本错位；
3. 统一 TypeScript 配置：根项目创建 tsconfig.base.json 作为基础配置，子项目通过 "extends": "../../tsconfig.base.json" 继承，保证类型检查规则一致。

七、实际配置总结

本次 Monorepo 实现的核心配置要点可归纳为以下三点，便于后续维护和扩展：

• 依赖模式：采用 node-modules 模式，兼容性强，避免 PnP 模式可能出现的工具适配问题；
• 命名规范：子项目统一使用 @wect/ 作用域前缀，清晰区分项目归属，避免命名冲突；
• 脚本统一：所有子项目定义一致的脚本命令（如 build、dev、test），确保批量操作顺畅。