Back to Details

moon

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

moon - Polyglot Monorepo Build System

moon - 多语言单体仓库构建系统

moon is a Rust-based repository management, task orchestration, and build system for polyglot monorepos. It provides smart caching, dependency-aware task execution, and unified toolchain management.
moon v2 is now available. Run 
moon migrate v2
to migrate. See 
references/v2-migration.md
for breaking changes.
moon是一个基于Rust的多语言单体仓库（monorepo）管理、任务编排和构建系统。它提供智能缓存、感知依赖的任务执行以及统一的工具链管理功能。
moon v2 现已发布。 运行 
moon migrate v2
进行迁移。请查看 
references/v2-migration.md
了解破坏性变更。

When to Use moon

适用场景

  • Managing monorepos with multiple projects/packages
  • Orchestrating tasks across projects with dependencies
  • Caching build outputs for faster CI/local builds
  • Managing toolchain versions (Node.js, Rust, Python, Go, etc.)
  • Generating project and action graphs
  • 管理包含多个项目/包的单体仓库
  • 跨依赖项目编排任务
  • 缓存构建输出以加速CI/本地构建
  • 管理工具链版本（Node.js、Rust、Python、Go等）
  • 生成项目和任务依赖图

Quick Reference

快速参考

Core Commands

核心命令

bash
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
bash
moon run <target>          # 运行任务
moon run :lint             # 在所有项目中运行
moon run '#tag:test'       # 按标签运行
moon ci                    # 针对CI优化的执行模式
moon check --all           # 运行所有构建/测试任务
moon query projects        # 列出所有项目
moon project-graph         # 可视化依赖关系

Target Syntax

目标语法

PatternDescription
project:task
Specific project and task
:task
All projects with this task
#tag:task
Projects with tag
^:task
Upstream dependencies (in deps)
~:task
Current project (in configs)
模式描述
project:task
指定项目和任务
:task
在所有包含该任务的项目中运行
#tag:task
在带有指定标签的项目中运行
^:task
运行上游依赖项目的对应任务
~:task
运行当前项目的对应任务

Configuration Files

配置文件

FilePurpose
.moon/workspace.yml
Workspace settings, project discovery
.moon/toolchains.yml
Language versions, package managers (v2)
.moon/tasks/*.yml
Global inherited tasks (v2)
moon.yml
Project-level config and tasks
v2 Note: 
.moon/toolchain.yml
→ 
.moon/toolchains.yml
(plural), 
.moon/tasks.yml
→ 
.moon/tasks/*.yml
文件用途
.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

Workspace Configuration

工作区配置

yaml
undefined
yaml
undefined

.moon/workspace.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"
undefined
$schema: "https://moonrepo.dev/schemas/workspace.json"
projects:
  • "apps/*"
  • "packages/*"
vcs: client: "git" defaultBranch: "main"
pipeline: archivableTargets: - ":build" cacheLifetime: "7 days"
undefined

Project Configuration

项目配置

yaml
undefined
yaml
undefined

moon.yml

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)"
undefined
$schema: "https://moonrepo.dev/schemas/project.json"
language: "typescript" layer: "application" # v2版本：'type' 重命名为 '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版本：使用 'script' 支持Shell特性（管道、重定向等）

lint: script: "eslint . && prettier --check ."
test: command: "vitest run" inputs: - "@group(sources)" - "@group(tests)"
undefined

Layer Types (v2)

层级类型（v2版本）

LayerDescription
application
Apps, services
library
Shareable code
tool
CLIs, scripts
automation
E2E/integration tests
scaffolding
Templates, generators
configuration
Infra, config
层级描述
application
应用、服务
library
可共享代码库
tool
CLI工具、脚本
automation
端到端/集成测试
scaffolding
模板、生成器
configuration
基础设施、配置文件

Task Configuration

任务配置

Task Fields

任务字段

FieldDescription
command
Command to execute (string or array)
args
Additional arguments
deps
Task dependencies
inputs
Files for cache hashing
outputs
Files to cache
env
Environment variables
extends
Inherit from another task
preset
server
or 
utility
字段描述
command
要执行的命令（字符串或数组）
args
额外参数
deps
任务依赖
inputs
用于缓存哈希计算的文件
outputs
要缓存的文件
env
环境变量
extends
继承自其他任务的配置
preset
预设类型：
server
或 
utility

Task Inheritance

任务继承

Tasks can be inherited globally via 
.moon/tasks/*.yml
:
yaml
undefined
任务可通过 
.moon/tasks/*.yml
实现全局继承：
yaml
undefined

.moon/tasks/node.yml

.moon/tasks/node.yml

inheritedBy: toolchains: ["javascript", "typescript"]
fileGroups: sources: ["src/**/*"]
tasks: lint: command: "eslint ." inputs: ["@group(sources)"]

Projects control inheritance:

```yaml
inheritedBy: toolchains: ["javascript", "typescript"]
fileGroups: sources: ["src/**/*"]
tasks: lint: command: "eslint ." inputs: ["@group(sources)"]

项目可控制继承规则：

```yaml

moon.yml

moon.yml

workspace: inheritedTasks: include: ["lint", "test"] exclude: ["deploy"] rename: buildApp: "build"
undefined
workspace: inheritedTasks: include: ["lint", "test"] exclude: ["deploy"] rename: buildApp: "build"
undefined

Task Options

任务选项

yaml
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
yaml
tasks:
  example:
    command: "cmd"
    options:
      cache: true # 启用缓存
      runInCI: "affected" # 可选值：affected, always, only, false
      persistent: true # 长期运行进程
      retryCount: 2 # 失败后重试次数
      timeout: 300 # 超时时间（秒）
      mutex: "resource" # 独占锁
      priority: "high" # 优先级：critical, high, normal, low

Input Tokens

输入令牌

yaml
inputs:
  - "@group(sources)" # File group
  - "@globs(tests)" # Glob patterns
  - "/tsconfig.base.json" # Workspace root file
  - "$NODE_ENV" # Environment variable
yaml
inputs:
  - "@group(sources)" # 文件组
  - "@globs(tests)" # 全局匹配模式
  - "/tsconfig.base.json" # 工作区根目录文件
  - "$NODE_ENV" # 环境变量

Toolchain Configuration

工具链配置

yaml
undefined
yaml
undefined

.moon/toolchains.yml (v2: plural)

.moon/toolchains.yml (v2版本：复数形式)

$schema: "https://moonrepo.dev/schemas/toolchains.json"
$schema: "https://moonrepo.dev/schemas/toolchains.json"

JavaScript ecosystem (v2: required for node/bun/deno)

JavaScript生态（v2版本：node/bun/deno必填）

javascript: packageManager: "pnpm" inferTasksFromScripts: false
node: version: "20.10.0"
pnpm: version: "8.12.0"
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"
undefined
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"
undefined

Toolchain Tiers

工具链层级

TierDescriptionExamples
3Full managementNode.js, Bun, Deno, Rust, Go, Python
2Ecosystem integrationPHP, Ruby
1Project categorizationBash, Batch
0System executionCustom tools
层级描述示例
3完全管理Node.js、Bun、Deno、Rust、Go、Python
2生态系统集成PHP、Ruby
1项目分类Bash、Batch
0系统级执行自定义工具

CI Integration

CI集成

yaml
undefined
yaml
undefined

GitHub Actions

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 }}
undefined
  • uses: actions/checkout@v4 with: fetch-depth: 0 # 检测变更项目所需
  • 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 }}
undefined

Parallelization with Matrix

矩阵并行化

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

steps:
  - run: moon ci --job ${{ matrix.shard }} --job-total 4
yaml
strategy:
  matrix:
    shard: [0, 1, 2, 3]

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

Affected Detection

变更检测

bash
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
bash
moon run :test --affected             # 仅运行变更项目的任务
moon run :lint --affected --status staged  # 仅针对暂存文件
moon ci :test --base origin/main      # 与基准分支对比
moon query changed-files              # v2版本：从touched-files重命名

Docker Support

Docker支持

bash
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
bash
moon docker scaffold <project>     # 生成Docker分层配置
moon docker setup                  # 在Docker中安装工具链
moon docker prune                  # 清理生产环境无用资源
moon docker file <project>         # 生成Dockerfile

Moon Query Language (MQL)

Moon查询语言（MQL）

bash
undefined
bash
undefined

Filter projects

过滤项目

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

Operators: =, !=, , !, &&, ||

操作符：=, !=, , !, &&, ||

Fields: project, language, stack, tag, task, taskType

字段：project, language, stack, tag, task, taskType

undefined
undefined

Additional Resources

更多资源

For detailed configuration options, consult:
  • references/workspace-config.md
     - Complete workspace.yml reference
  • references/task-config.md
     - Task configuration and inheritance patterns
  • references/v2-migration.md
     - v1 to v2 migration guide
  • references/cli-reference.md
     - Full CLI command reference
如需详细配置选项，请参考：
  • references/workspace-config.md
     - 完整的workspace.yml配置参考
  • references/task-config.md
     - 任务配置与继承模式
  • references/v2-migration.md
     - v1到v2迁移指南
  • references/cli-reference.md
     - 完整CLI命令参考

Examples

示例

  • examples/workspace.yml
     - Complete workspace configuration
  • examples/moon.yml
     - Full project configuration
  • examples/ci-workflow.yml
     - GitHub Actions CI workflow
  • examples/workspace.yml
     - 完整工作区配置示例
  • examples/moon.yml
     - 完整项目配置示例
  • examples/ci-workflow.yml
     - GitHub Actions CI工作流示例