知识库

Appearance

Return to top
On this page

Monorepo 速查表

常用命令

pnpm Workspaces

bash
# 安装依赖
pnpm install

# 在所有包中运行脚本
pnpm --recursive run test
pnpm -r run build

# 在特定包中运行脚本
pnpm --filter <package-name> run dev

# 添加依赖到特定包
pnpm --filter <package-name> add <dependency>

# 运行受影响的包
pnpm --filter "...[origin/main]" build

Yarn Workspaces

bash
# 安装依赖
yarn install

# 在所有工作区运行脚本
yarn workspaces run test

# 在特定工作区运行脚本
yarn workspace <package-name> run dev

# 添加依赖到特定工作区
yarn workspace <package-name> add <dependency>

Nx

bash
# 构建特定项目
nx build my-app

# 运行受影响的测试
nx affected:test

# 查看依赖图
nx dep-graph

# 生成代码
nx generate @nx/react:component my-component --project=my-lib

# 运行自定义目标
nx affected --target=custom-target

Lerna

bash
# 安装依赖
lerna bootstrap

# 运行脚本
lerna run build

# 发布包
lerna publish

# 独立版本发布
lerna publish --independent

# 从 Git 发布
lerna publish from-git

配置文件

pnpm-workspace.yaml

yaml
packages:
  # 所有 packages/ 目录下的包
  - 'packages/*'
  # 排除测试包
  - '!**/test/**'
  # 包含 examples/ 目录下的包
  - 'examples/**'

nx.json

json
{
  "npmScope": "myorg",
  "affected": {
    "defaultBase": "master"
  },
  "tasksRunnerOptions": {
    "default": {
      "runner": "@nx/workspace/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test", "e2e"]
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    }
  }
}

rush.json

json
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",
  "rushVersion": "5.70.0",
  "pnpmVersion": "6.7.1",
  "projects": [
    {
      "packageName": "my-app",
      "projectFolder": "apps/my-app",
      "shouldPublish": true,
      "versionPolicyName": "library-policy"
    }
  ]
}

包管理最佳实践

依赖提升

json
// 根目录 package.json
{
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "devDependencies": {
    "typescript": "^4.9.0",
    "@types/node": "^18.0.0",
    "eslint": "^8.0.0"
  }
}

内部包引用

json
// 包的 package.json
{
  "name": "@myorg/web-app",
  "dependencies": {
    "@myorg/ui-components": "workspace:*",
    "@myorg/utils": "workspace:~1.0.0",
    "external-dep": "^2.0.0"
  }
}

常用脚本

package.json 脚本

json
{
  "scripts": {
    "build": "pnpm --recursive run build",
    "build:affected": "nx affected:build",
    "test": "pnpm --recursive run test",
    "test:affected": "nx affected:test",
    "lint": "pnpm --recursive run lint",
    "lint:affected": "nx affected:lint",
    "dev": "pnpm --filter dev-app run dev",
    "clean": "rm -rf node_modules && pnpm --recursive run clean"
  }
}

Git 工作流

Git 配置

bash
# 设置 Git 提交模板
git config commit.template .gitmessage

# 配置 Git 别名
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch

常用 Git 命令

bash
# 查看受影响的文件
git diff --name-only origin/main HEAD

# 查看特定目录的更改
git diff --name-only origin/main HEAD -- packages/core/

# 暂存特定包的更改
git add packages/my-package/

代码组织

目录结构 

monorepo/
├── apps/                 # 应用程序
│   ├── web-app/
│   └── admin-panel/
├── packages/            # 可复用包
│   ├── ui-components/
│   ├── utils/
│   └── data-access/
├── tools/               # 构建工具
├── docs/                # 文档
├── scripts/             # 自定义脚本
├── .github/
│   └── workflows/       # CI/CD 工作流
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.base.json   # 共享 TS 配置

CI/CD 配置

GitHub Actions 示例

yaml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x, 18.x]
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm nx affected:test --base=origin/main
      - run: pnpm nx affected:lint

性能优化

缓存策略

json
// package.json
{
  "scripts": {
    "cache:restore": "cache-restore",
    "cache:save": "cache-save"
  }
}

并行执行

bash
# 并行运行测试
jest --maxWorkers=50%

# 并行构建
pnpm --recursive --parallel run build

# 限制并行度
nx build my-app --maxParallel=2

调试技巧

调试特定包

bash
# 只调试特定包
pnpm --filter my-package run debug

# 调试受影响的包
nx affected --target=debug

日志和调试信息

bash
# 详细输出
pnpm install --reporter=append-only

# 调试模式
nx build my-app --verbose

# 检查依赖
pnpm why <package-name>

常见问题解决

依赖冲突

bash
# 检查依赖
pnpm why <package-name>

# 强制特定版本
pnpm install <package-name>@<version> --save-exact

# 清理并重新安装
pnpm store prune && pnpm install

清理缓存

bash
# 清理 pnpm 存储
pnpm store prune

# 清理 Nx 缓存
npx nx reset

# 清理构建输出
pnpm --recursive run clean

安全检查

依赖安全扫描

bash
# npm 审计
npm audit
npm audit fix

# 使用 Snyk
npx snyk test
npx snyk monitor

机密扫描

bash
# 使用 detect-secrets
npx detect-secrets-hook --baseline .secrets.baseline

版本管理

语义化版本

  • MAJOR.MINOR.PATCH 格式
  • BREAKING.CHANGES.FEATURES 对应
  • 使用 ^ 或 ~ 控制更新范围

发布标签

bash
# 创建 Git 标签
git tag v1.0.0
git push origin v1.0.0

# 预发布标签
git tag v1.0.0-beta.1

资源链接

检查清单

项目启动前

  • [ ] 选择合适的 monorepo 工具
  • [ ] 设计项目结构
  • [ ] 配置共享设置
  • [ ] 设置 CI/CD 流程

日常开发

  • [ ] 使用影子命令优化工作流
  • [ ] 定期更新依赖
  • [ ] 运行测试和 lint
  • [ ] 检查安全性

发布前

  • [ ] 运行所有测试
  • [ ] 检查依赖安全性
  • [ ] 验证构建成功
  • [ ] 更新文档
  • [ ] 创建变更日志