moon

moon - 多语言 Monorepo 构建系统

moon 是一款基于 Rust 的仓库管理、任务编排和构建系统，适用于多语言 Monorepo。它提供智能缓存、依赖感知的任务执行，以及统一的工具链管理。

moon v2 现已推出。 运行 moon migrate v2 进行迁移。有关不兼容变更，请参阅 references/v2-migration.md。

何时使用 moon

• 管理包含多个项目／软件包的 Monorepo
• 编排跨项目且存在依赖关系的任务
• 缓存构建输出，加快 CI／本地构建
• 管理工具链版本（Node.js、Rust、Python、Go 等）
• 生成项目图和操作图

快速参考

核心命令

moon run <target>          # Run task(s)
moon run :lint             # Run in all projects
moon run '#tag:test'       # Run by tag
moon ci                    # CI-optimized execution
moon check --all           # Run all build/test tasks
moon query projects        # List projects
moon project-graph         # Visualize dependencies

目标语法

模式	描述
project:task	指定项目和任务
:task	所有包含此任务的项目
#tag:task	带有此标签的项目
^:task	上游依赖项（在 deps 中）
~:task	当前项目（在配置中）

配置文件

文件	用途
.moon/workspace.yml	工作区设置、项目发现
.moon/toolchains.yml	语言版本、包管理器（v2）
.moon/tasks/*.yml	全局继承的任务（v2）
moon.yml	项目级配置和任务

v2 注意： .moon/toolchain.yml → .moon/toolchains.yml（复数），.moon/tasks.yml → .moon/tasks/*.yml

工作区配置

# .moon/workspace.yml
$schema: "https://moonrepo.dev/schemas/workspace.json"

projects:
  - "apps/*"
  - "packages/*"

vcs:
  client: "git"
  defaultBranch: "main"

pipeline:
  archivableTargets:
    - ":build"
  cacheLifetime: "7 days"

项目配置

# moon.yml
$schema: "https://moonrepo.dev/schemas/project.json"

language: "typescript"
layer: "application" # v2: 'type' renamed to 'layer'
stack: "frontend"
tags: ["react", "graphql"]

dependsOn:
  - "shared-utils"
  - id: "api-client"
    scope: "production"

fileGroups:
  sources:
    - "src/**/*"
  tests:
    - "tests/**/*"

tasks:
  build:
    command: "vite build"
    inputs:
      - "@group(sources)"
    outputs:
      - "dist"
    deps:
      - "^:build"

  dev:
    command: "vite dev"
    preset: "server"

  # v2: Use 'script' for shell features (pipes, redirects)
  lint:
    script: "eslint . && prettier --check ."

  test:
    command: "vitest run"
    inputs:
      - "@group(sources)"
      - "@group(tests)"

层类型（v2）

层	描述
application	应用、服务
library	可共享的代码
tool	CLI、脚本
automation	端到端／集成测试
scaffolding	模板、生成器
configuration	基础设施、配置

任务配置

任务字段

字段	描述
command	要执行的命令（字符串或数组）
args	附加参数
deps	任务依赖项
inputs	用于缓存哈希的文件
outputs	要缓存的文件
env	环境变量
extends	继承自另一个任务
preset	server 或 utility

任务继承

可通过 .moon/tasks/*.yml 全局继承任务：

# .moon/tasks/node.yml
inheritedBy:
  toolchains: ["javascript", "typescript"]

fileGroups:
  sources: ["src/**/*"]

tasks:
  lint:
    command: "eslint ."
    inputs: ["@group(sources)"]

项目可控制继承：

# moon.yml
workspace:
  inheritedTasks:
    include: ["lint", "test"]
    exclude: ["deploy"]
    rename:
      buildApp: "build"

任务选项

tasks:
  example:
    command: "cmd"
    options:
      cache: true # Enable caching
      runInCI: "affected" # affected, always, only, false
      persistent: true # Long-running process
      retryCount: 2 # Retry on failure
      timeout: 300 # Seconds
      mutex: "resource" # Exclusive lock
      priority: "high" # critical, high, normal, low

输入令牌

inputs:
  - "@group(sources)" # File group
  - "@globs(tests)" # Glob patterns
  - "/tsconfig.base.json" # Workspace root file
  - "$NODE_ENV" # Environment variable

工具链配置

# .moon/toolchains.yml (v2: plural)
$schema: "https://moonrepo.dev/schemas/toolchains.json"

# JavaScript ecosystem (v2: required for node/bun/deno)
javascript:
  packageManager: "pnpm"
  inferTasksFromScripts: false

node:
  version: "20.10.0"

pnpm:
  version: "8.12.0"

# Alternative runtimes
bun:
  version: "1.0.0"

deno:
  version: "1.40.0"

typescript:
  syncProjectReferences: true
  routeOutDirToCache: true

rust:
  version: "1.75.0"
  bins: ["cargo-nextest", "cargo-llvm-cov"]

go:
  version: "1.21.0"

python:
  version: "3.12.0"

工具链层级

层级	描述	示例
3	全面管理	Node.js、Bun、Deno、Rust、Go、Python
2	生态系统集成	PHP、Ruby
1	项目分类	Bash、Batch
0	系统执行	自定义工具

CI 集成

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # Required for affected detection

- uses: moonrepo/setup-toolchain@v0
  with:
    auto-install: true

- run: moon ci :build :test

- uses: moonrepo/run-report-action@v1
  if: success() || failure()
  with:
    access-token: ${{ secrets.GITHUB_TOKEN }}

使用矩阵并行化

strategy:
  matrix:
    shard: [0, 1, 2, 3]

steps:
  - run: moon ci --job ${{ matrix.shard }} --job-total 4

受影响项检测

moon run :test --affected             # Only affected projects
moon run :lint --affected --status staged  # Only staged files
moon ci :test --base origin/main      # Compare against base
moon query changed-files              # v2: renamed from touched-files

Docker 支持

moon docker scaffold <project>     # Generate Docker layers
moon docker setup                  # Install toolchain in Docker
moon docker prune                  # Prune for production
moon docker file <project>         # Generate Dockerfile

Moon 查询语言（MQL）

# Filter projects
moon query projects "language=typescript && projectType=library"
moon run :build --query "tag=react"

# Operators: =, !=, ~, !~, &&, ||
# Fields: project, language, stack, tag, task, taskType

更多资源

有关详细配置选项，请参阅：

• references/workspace-config.md - 完整的 workspace.yml 参考
• references/task-config.md - 任务配置和继承模式
• references/v2-migration.md - 从 v1 迁移到 v2 的指南
• references/cli-reference.md - 完整的 CLI 命令参考

示例

• examples/workspace.yml - 完整的工作区配置
• examples/moon.yml - 完整的项目配置
• examples/ci-workflow.yml - GitHub Actions CI 工作流