Lage

Microsoft 出品的轻量级 JavaScript/TypeScript Monorepo 任务编排工具，基于依赖图实现并行执行与智能缓存。

技术简介说明

Lage（挪威语意为"制造"，发音 law-geh）是微软开源的一款专为 JavaScript/TypeScript Monorepo 设计的任务编排与构建工具。它的核心设计理念是"极简配置，开箱即用"，通过自动解析工作区包之间的依赖关系，构建有向无环图（DAG），实现任务的并行调度、增量构建和结果缓存。与同类工具相比，Lage 专注于"做好一件事"——任务编排，不捆绑代码生成、项目脚手架或框架绑定等额外能力，使其成为纯任务运行场景下的轻量级选择。

Lage 的核心价值在于显著缩短大型 Monorepo 的 CI/CD 构建时间。它通过本地缓存和可插拔的远程缓存（支持 S3、Azure Blob Storage 等云存储后端），确保开发者无需重复执行已完成的任务。当代码未发生变化时，Lage 会自动跳过构建、测试、lint 等操作，在团队协作和 CI 环境中可以带来数倍甚至数十倍的构建速度提升。

作为微软内部大规模 Monorepo（如 Office、Fluent UI 等）实际验证的工具，Lage 在生产环境中经历了严格的性能考验。它完美支持 npm、yarn、pnpm 和 Rush 等主流 Monorepo 管理方案，能够无缝集成到现有的 JavaScript/TypeScript 工程体系中。

基本信息

快速上手

安装

在 Monorepo 根目录下执行以下命令：

# 使用 npx 一键初始化（推荐）
npx lage init
 
# 或手动安装为开发依赖
npm install -D lage
yarn add -D lage
pnpm add -D lage

npx lage init 会自动完成以下操作：

• 安装 lage 包作为开发依赖
• 生成默认的 lage.config.js 配置文件

基础配置

配置文件（lage.config.js）

// lage.config.js
module.exports = {
  // 任务管道定义：声明任务之间的依赖关系
  pipeline: {
    // ^build 表示先执行所有依赖包的 build 任务
    build: ["^build"],
    // test 依赖于当前包的 build 完成
    test: ["build"],
    // lint 无前置依赖，可独立并行执行
    lint: [],
    // 自定义任务示例
    "typecheck": ["^build"],
  },
 
  // 缓存选项
  cacheOptions: {
    // 需要缓存的产物文件 glob 模式
    outputGlob: ["dist/**", "lib/**", "build/**"],
    // 当这些文件变化时使缓存失效
    environmentGlob: [".env*", "tsconfig.json", "lage.config.js"],
  },
};

更新 package.json scripts

{
  "scripts": {
    "build": "lage build",
    "test": "lage test",
    "lint": "lage lint",
    "typecheck": "lage typecheck"
  }
}

最小示例

以下是一个最简的 pnpm workspace Monorepo 示例：

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── lage.config.js
└── packages/
    ├── core/          # 基础库
    │   └── package.json
    ├── utils/         # 工具库，依赖 core
    │   └── package.json
    └── app/           # 应用，依赖 core 和 utils
        └── package.json

# pnpm-workspace.yaml
packages:
  - "packages/*"

// lage.config.js
module.exports = {
  pipeline: {
    build: ["^build"],
    test: ["^build"],
  },
  cacheOptions: {
    outputGlob: ["dist/**"],
  },
};

执行构建：

# 所有包的 build 任务会按依赖拓扑顺序并行执行
pnpm build
 
# 运行测试
pnpm test
 
# 查看任务执行图（调试用）
npx lage graph --task build

核心概念与架构

核心概念

1. 目标（Target）

目标是 Lage 中最基本的执行单元，由"包名 + 任务名"唯一标识。例如 core#build 表示 core 包的 build 任务。每个目标具有以下属性：

• 任务名称：对应 package.json 中的 script 名称
• 依赖关系：声明该目标执行前需完成的其他目标
• 缓存配置：定义缓存命中条件和输出文件

2. 依赖图（Target Graph）

Lage 在运行时自动分析工作区中所有包的依赖关系，构建一个有向无环图（DAG）。图的节点是各个 Target，边表示执行顺序约束。Lage 基于此图进行拓扑排序，决定任务的执行顺序。

3. 管道（Pipeline）

管道是 lage.config.js 中定义的任务编排规则。它声明了各任务之间的依赖关系：

• [] — 无依赖，可立即执行
• ["^build"] — 先执行所有依赖包的 build 任务（^ 前缀表示依赖包）
• ["build"] — 先执行当前包的 build 任务

4. 缓存（Cache）

Lage 通过哈希算法计算每个目标的"缓存指纹"，考虑因素包括：

• 源代码文件内容
• 依赖包的缓存状态
• 环境变量和配置文件（environmentGlob）
• 任务命令本身

当缓存命中时，Lage 直接恢复产物文件，跳过任务执行。

5. Worker 池

Lage v2 引入了轻量级 Worker 池架构，通过多进程并行执行任务。Worker 池的大小默认根据 CPU 核心数自动调节，也可手动配置。

架构设计

┌─────────────────────────────────────────────────┐
│                    CLI 入口                       │
│              (lage build / lage test)             │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              工作区发现与依赖解析                    │
│   (读取 package.json / workspace 配置)            │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              目标图构建 (Target Graph)              │
│   (基于 pipeline 配置构建 DAG)                     │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              缓存检查 (Cache Lookup)               │
│   (计算哈希 → 查本地缓存 → 查远程缓存)              │
└──────────────────────┬──────────────────────────┘
                       │
         ┌─────────────┴─────────────┐
         │ 缓存命中                    │ 缓存未命中
         ▼                           ▼
┌─────────────────┐      ┌───────────────────────┐
│ 恢复缓存产物     │      │   Worker 池调度执行      │
│ (跳过任务)       │      │   (多进程并行执行)       │
└─────────────────┘      └───────────┬───────────┘
                                     │
                           ┌─────────▼─────────┐
                           │  写入缓存           │
                           │  (本地 + 远程)       │
                           └───────────────────┘

核心特性

1. 智能任务编排

基于依赖图自动解析任务执行顺序，支持复杂的跨包依赖关系。^ 前缀语法简洁地表达"先构建依赖"的语义，无需手动指定拓扑顺序。

2. 并行执行

独立任务自动并行执行，充分利用多核 CPU。Worker 池架构支持灵活的任务调度和负载均衡，显著缩短整体构建时间。

3. 本地缓存

内置高效的本地缓存系统，基于内容哈希（非时间戳）判断任务是否需要重新执行。缓存命中时直接恢复产物文件，实现毫秒级"构建"。

4. 远程缓存（可插拔）

支持自定义远程缓存后端，通过 @lage-run/cache 包可接入：

• AWS S3 — 适合 AWS 基础设施团队
• Azure Blob Storage — 适合 Azure/Microsoft 生态
• 自定义 Provider — 通过 Node.js API 实现任意缓存后端

远程缓存使团队成员和 CI 机器之间共享构建产物，新开发者克隆仓库后可直接复用已有缓存。

5. 远程回退缓存（Remote Fallback Cache）

v2 新增特性：本地缓存未命中时，自动回退到远程缓存获取产物，而非重新执行任务。这在团队开发和 CI 环境中极大减少重复构建。

6. 任务跳过（Task Skipping）

通过 --to、--from、--since 等过滤器，可以精确控制需要执行的任务范围：

# 只构建 app 包及其依赖
lage build --to app
 
# 只构建自上次提交以来有变更的包
lage build --since HEAD~1
 
# 从指定包开始，构建它及所有依赖它的包
lage build --from utils

7. 自定义管道配置

支持按任务粒度配置管道规则，不同任务可以有不同的依赖策略：

pipeline: {
  build: ["^build"],           // 先构建依赖
  test: ["build"],             // 先构建自身
  lint: [],                    // 无依赖
  deploy: ["build", "test"],   // 多依赖
}

8. 任务优先级

支持为任务设置优先级，确保关键任务优先执行：

pipeline: {
  build: {
    deps: ["^build"],
    priority: 1,  // 高优先级
  },
  lint: {
    deps: [],
    priority: 0,  // 普通优先级
  },
}

9. 可视化任务图

内置任务图可视化功能，帮助开发者理解 Monorepo 中的依赖关系：

npx lage graph --task build

10. 丰富的输出格式

支持多种输出模式：

• 摘要模式（默认） — 只显示每个任务的最终状态
• 详细模式 — 实时显示每个任务的完整输出
• JSON 模式 — 机器可读的 JSON 输出，便于 CI 集成

生态图

核心包（@lage-run/*）

Lage v2 将核心能力拆分为独立的可复用包，开发者可按需引用：

社区生态

• 缓存 Provider 插件：社区贡献了 S3、Azure Blob、GitHub Actions Cache 等远程缓存后端
• CI 集成模板：GitHub Actions、Azure Pipelines、GitLab CI 的 Lage 集成示例
• Rush Stack 生态：作为微软 Rush Stack 工具链的一部分，与 Rush、Heft 等工具协同工作

与 Microsoft 工具链的关系

┌─────────────────────────────────────────┐
│           Microsoft Rush Stack           │
│  ┌───────┐  ┌──────┐  ┌──────┐         │
│  │ Rush  │  │ Heft │  │ Lage │         │
│  │(版本管理)│  │(构建) │  │(编排) │         │
│  └───────┘  └──────┘  └──────┘         │
└─────────────────────────────────────────┘

Lage 可以独立使用，也可以作为 Rush Stack 的一部分，与 Rush（版本管理与发布）和 Heft（单包构建工具）搭配使用。

适用场景

1. JavaScript/TypeScript Monorepo 构建编排

典型场景：包含数十到数百个包的大型前端 Monorepo，需要高效协调 TypeScript 编译、打包、测试等任务。 示例：微软 Office Web 客户端、Fluent UI 组件库。

2. CI/CD 构建加速

典型场景：CI 流水线中通过远程缓存共享构建产物，PR 构建只执行变更相关的任务，大幅缩短 CI 等待时间。 效果：大型项目 CI 时间可从 30+ 分钟降至 5 分钟以内。

3. 团队协作开发环境优化

典型场景：多人协作开发时，通过远程缓存避免每位开发者都从零构建。新成员克隆仓库后直接复用团队缓存，首次构建从分钟级降到秒级。

4. 增量构建与变更检测

典型场景：Monorepo 中某个基础库变更时，自动识别所有受影响的包并仅重新构建这些包，而非全量构建。

5. 多阶段发布流水线

典型场景：需要按顺序执行 build → test → lint → typecheck → deploy 的复杂发布流程，各阶段之间有明确的依赖关系。

6. 与 Rush 配合的版本管理场景

典型场景：使用 Rush 管理包版本和发布，使用 Lage 处理构建任务编排，两者互补形成完整的 Monorepo 管理方案。

7. 多包并行开发调试

典型场景：开发者同时修改多个相互依赖的包，Lage 自动按依赖顺序构建，避免手动管理构建顺序。

开发与工程化

开发流程

本地开发

# 克隆项目
git clone https://github.com/microsoft/lage.git
cd lage
 
# 安装依赖（项目使用 Rush 管理）
npm install -g @microsoft/rush
rush install
 
# 构建
rush build
 
# 运行测试
rush test

配置远程缓存（以 AWS S3 为例）

// lage.config.js
const { S3CacheProvider } = require("@lage-run/cache");
 
module.exports = {
  pipeline: {
    build: ["^build"],
    test: ["build"],
  },
  cacheOptions: {
    outputGlob: ["dist/**"],
  },
  // 远程缓存配置
  cacheProvider: new S3CacheProvider({
    bucket: "my-lage-cache",
    region: "us-east-1",
    // 使用 IAM 角色或环境变量认证
  }),
};

CI/CD 集成

GitHub Actions

name: Build
on: [push, pull_request]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Lage 需要完整 git 历史进行变更检测
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - uses: pnpm/action-setup@v4
        with:
          version: 9
 
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
 
      - name: Build with cache
        run: pnpm lage build
        env:
          # 启用远程缓存
          LAGE_CACHE_PROVIDER: s3
          AWS_S3_BUCKET: ${{ secrets.CACHE_BUCKET }}
          AWS_REGION: us-east-1
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Azure Pipelines

trigger:
  - main
 
pool:
  vmImage: "ubuntu-latest"
 
steps:
  - task: NodeTool@0
    inputs:
      versionSpec: "22.x"
 
  - script: npm ci
    displayName: "Install dependencies"
 
  - script: npx lage build
    displayName: "Build with Lage"
    env:
      LAGE_CACHE_PROVIDER: azure-blob
      AZURE_STORAGE_ACCOUNT: $(CACHE_STORAGE_ACCOUNT)
      AZURE_STORAGE_SAS_TOKEN: $(CACHE_SAS_TOKEN)

调试技巧

# 查看任务执行图（不实际执行）
npx lage graph --task build
 
# 详细输出模式
npx lage build --verbose
 
# 禁用缓存（调试时）
npx lage build --no-cache
 
# 只执行特定包的任务
npx lage build --to @myorg/utils
 
# 查看缓存命中率
npx lage build --profile

性能与安全

性能特点

性能优化建议

1. 合理配置 outputGlob：只缓存必要的产物文件，避免缓存过大导致传输慢
2. 利用 --since 过滤器：CI 中只构建变更的包及下游依赖
3. 远程缓存预热：在 CI 主分支构建时主动推送到远程缓存，开发者本地自动拉取
4. 避免过度依赖：扁平化包依赖结构，减少 DAG 深度，提高并行度
5. 合理设置 Worker 数量：通过 --concurrency 参数控制，避免 I/O 瓶颈

安全注意事项

1. 远程缓存安全：

   • 使用 IAM 角色/短期凭据（SAS Token、STS）而非长期密钥
   • 确保缓存 Bucket 的访问权限最小化
   • 敏感环境变量应纳入 environmentGlob 使缓存正确失效

2. 缓存隔离：

   • 远程缓存按分支/PR 隔离，避免不同分支的缓存互相污染
   • 使用哈希策略确保不同代码版本不会错误命中缓存

3. 供应链安全：

   • @lage-run/* 包均为微软官方维护，注意检查包名拼写防止 typosquatting
   • 锁定版本，使用 package-lock.json 或 pnpm-lock.yaml

已知性能瓶颈

• 超大 Monorepo（> 5000 包）：依赖图构建可能成为瓶颈，建议拆分为多层 Monorepo
• 网络延迟：远程缓存拉取在低带宽环境下可能成为瓶颈
• 大量小文件：缓存恢复时大量小文件可能导致文件系统 I/O 瓶颈

技术对比

与主流 Monorepo 工具对比

选型建议

• 选 Lage：纯 JavaScript/TypeScript Monorepo，需要简单配置、自带远程缓存（无需第三方服务）、与微软生态（Rush、Azure）深度集成
• 选 Turborepo：追求极致构建速度（Rust 内核），团队使用 Vercel 部署，偏好"约定优于配置"
• 选 Nx：超大型 Monorepo，需要代码生成、精细的依赖图分析、模块边界治理，愿意使用 Nx Cloud
• 选 Bazel：多语言 Monorepo（Go/Rust/Java/Python 混合），超大规模（数千模块），有专职 DevOps 团队
• 选 moon：追求现代工具体验（Rust 内核），需要开箱即用的工具链管理，偏好显式配置

最佳实践

生产环境最佳实践

1. 始终配置远程缓存

   // lage.config.js
   module.exports = {
     cacheProvider: new RemoteCacheProvider({
       // 生产环境务必配置远程缓存
       // 使团队和 CI 共享构建成果
     }),
   };

2. CI 中使用 --since 增量构建

   # PR 构建：只构建变更相关包
   lage build --since origin/main

3. 合理拆分 outputGlob

   cacheOptions: {
     // ✅ 只缓存必要产物
     outputGlob: ["dist/**", "lib/**/*.js", "lib/**/*.d.ts"],
     // ❌ 避免缓存整个 node_modules 或临时文件
     // outputGlob: ["**/*"],
   }

4. 主分支构建时预热缓存

   # CI 中主分支构建后主动推送缓存
   - script: npx lage build --no-cache  # 确保缓存最新

5. 使用 --profile 分析性能瓶颈

   # 生成任务执行 profile 报告
   lage build --profile
   # 分析哪些任务耗时最长，优化依赖关系

常见陷阱

1. ⚠️ 忽略 environmentGlob 配置

   • 问题：修改 tsconfig.json 后缓存未失效，导致构建产物不正确
   • 解决：将所有影响构建输出的配置文件加入 environmentGlob

2. ⚠️ 缓存中包含绝对路径

   • 问题：不同开发者/CI 机器上绝对路径不同，缓存永远不命中
   • 解决：确保构建脚本不输出绝对路径到产物文件

3. ⚠️ 过度使用 --no-cache

   • 问题：开发时频繁禁用缓存，失去增量构建优势
   • 解决：只在调试缓存问题时使用 --no-cache

4. ⚠️ 忽视依赖图深度

   • 问题：过深的依赖链（A → B → C → D → E）限制了并行度
   • 解决：扁平化包结构，减少不必要的中间包

5. ⚠️ 远程缓存凭据泄露

   • 问题：将 S3/Azure 密钥硬编码到配置文件
   • 解决：使用环境变量或 IAM 角色，将凭据文件加入 .gitignore

推荐模式

┌─ 推荐的 Lage 项目结构 ──────────────────────┐
│                                              │
│  my-monorepo/                               │
│  ├── lage.config.js          # 集中式管道配置 │
│  ├── package.json            # 根 scripts 入口 │
│  ├── pnpm-workspace.yaml    # 工作区声明      │
│  ├── .github/workflows/     # CI 集成        │
│  │   └── build.yml                           │
│  └── packages/                               │
│      ├── core/                               │
│      │   ├── package.json                    │
│      │   └── src/                            │
│      └── app/                                │
│          ├── package.json                    │
│          └── src/                            │
│                                              │
│  ✅ 每个包独立 package.json                   │
│  ✅ 根目录统一 lage.config.js                 │
│  ✅ 远程缓存始终配置                           │
│  ✅ CI 使用 --since 增量构建                  │
└──────────────────────────────────────────────┘

技术局限与边界

已知限制

1. 仅支持 JavaScript/TypeScript 生态

   • Lage 的设计围绕 npm/yarn/pnpm 工作区，不支持 Python、Go、Rust 等其他语言
   • 如果 Monorepo 包含多语言项目，需考虑 Bazel、moon 或 Nx

2. 远程缓存需要自建后端

   • 与 Turborepo（Vercel 托管）和 Nx（Nx Cloud 托管）不同，Lage 不提供托管远程缓存服务
   • 需要团队自行配置 S3、Azure Blob 等存储后端，增加运维成本

3. 社区规模相对较小

   • GitHub Stars 约 2.4k，社区活跃度和第三方插件生态不如 Turborepo 和 Nx
   • 遇到问题时社区支持资源较少，更依赖官方文档和 Issues

4. 代码生成与脚手架缺失

   • Lage 定位为纯任务编排工具，不提供项目生成、模块脚手架等能力
   • 如需代码生成，需搭配其他工具（如 Plop、Hygen）或切换到 Nx

5. 大仓库性能上限

   • 超过 5000 个包时，依赖图构建和变更检测性能可能下降
   • 微软内部的大规模场景通常搭配 Rush 使用，单独使用 Lage 可能面临扩展性挑战

不适用场景

• 多语言 Monorepo：包含 Go、Rust、Python 等非 JS 语言的项目
• 超大规模 Monorepo（> 10000 包）：应考虑 Bazel 或定制方案
• 需要托管远程缓存：不想自建缓存基础设施的团队，Turborepo + Vercel 或 Nx + Nx Cloud 更合适
• 需要代码生成与架构治理：需要模块生成、边界检查、依赖约束等能力时，Nx 是更好的选择
• 非 JavaScript 生态系统：Java/Kotlin（Gradle）、C/C++（CMake）等应使用原生构建工具

迁移注意事项

• 从 Turborepo 迁移：配置文件格式不同（turbo.json → lage.config.js），管道语法需重写
• 从 Lerna 迁移：Lerna v6+ 底层已使用 Nx，迁移到 Lage 需重新配置任务管道
• 从零开始：Lage 的 npx lage init 提供了最低的学习成本，建议新项目评估
• 渐进式采用：Lage 可以逐步引入，先在部分包中启用，不影响现有构建流程

学习资源

官方文档

• Lage 官方文档 — 完整的配置参考和指南
• 快速入门 — 5 分钟上手指南
• GitHub 仓库 — 源代码、Issues、RFC 讨论
• RELEASE.md — 版本发布记录

教程与博客

• Monorepos with Microsoft Lage: Learnings This Week — 实战经验分享（Elf Sternberg）
• Lage 演示幻灯片 — 官方演示文稿

社区资源

• monorepo.tools - Compare Monorepo Tools — 多工具功能对比
• GitHub Discussions — 官方讨论区
• GitHub Issues — Bug 报告和功能请求

相关工具

• Rush — 微软的 Monorepo 版本管理工具
• Heft — 微软的单包构建工具
• Rush Stack — 微软 Monorepo 工具链全家桶

2026 年现状

最新版本

• 当前版本：v2.15.12（2026年6月18日发布）
• @lage-run/ 包版本*：
  • @lage-run/cache: 1.4.6
  • @lage-run/target-graph: 0.14.1
  • @lage-run/runners: 1.4.9
  • @lage-run/reporters: 1.8.0
  • @lage-run/logger: 1.5.0

发展趋势

1. 稳定维护期：Lage 目前处于稳定的维护迭代阶段，以 bug 修复和小幅改进为主，每 2-4 周发布一个补丁版本
2. Rust 化趋势：同类工具（Turborepo、moon）都在将核心迁移到 Rust 以提升性能，Lage 目前仍为纯 JavaScript 实现，未来是否跟进 Rust 化尚不明确
3. 远程缓存生态：社区持续丰富远程缓存 Provider 的支持，S3、Azure Blob、GitHub Actions Cache 等后端日趋成熟
4. Rush Stack 整合：作为微软 Rush Stack 生态的一部分，Lage 与 Rush、Heft 的协同使用场景持续深化

社区活跃度

• GitHub Stars：约 2,400+
• 维护状态：活跃维护，微软内部持续使用
• Issue 响应：官方团队响应及时，RFC 讨论活跃（如 RFC #816 Pipeline definition merging）
• NPM 下载量：稳定增长，在大型 JavaScript Monorepo 中有一定的采用率

未来路线图

根据 GitHub RFC 和 Issues 中的讨论，社区关注的方向包括：

• Pipeline 定义合并（RFC #816）：支持多个配置文件中的管道规则合并
• Worker 类型扩展：更多自定义 Worker 类型支持
• 性能优化：依赖图计算和缓存哈希算法的持续优化
• 更好的 CI 集成：原生支持更多 CI 平台的缓存和变更检测特性

竞品动态

2026 年 Monorepo 工具领域的主要趋势：

• Turborepo 继续凭借 Vercel 生态和 Rust 内核保持速度优势
• Nx 通过 Nx Cloud 和 AI 辅助调试功能扩展企业级能力
• moon 作为新锐 Rust 工具快速崛起，追求开箱即用体验
• Lage 保持在微软生态和纯任务编排场景中的独特定位，以简洁和可插拔性为核心竞争力

参考资料：

• Lage 官方文档
• GitHub - microsoft/lage
• NPM - lage
• monorepo.tools - Compare Monorepo Tools
• Monorepos with Microsoft Lage
• RFC #254: Lage v2 - breaking apart the builder
• RFC #816: Pipeline definition merging