Nx logo

Nx

面向现代开发团队的 Monorepo 平台,通过智能任务编排、分布式缓存和 AI 驱动的自愈 CI,显著加速大型代码库的构建与协作。

精选工具MonorepoAI智能编排分布式缓存

Nx 是由前 Angular CLI 团队创建的开源 Monorepo 构建系统,灵感源自 Bazel 但专注 JS/TS 生态。通过 project graph 实现精准增量构建,配合远程缓存将 CI 时间从数十分钟压缩到数秒,并已集成 AI Agent 能力。

Nx

面向现代开发团队的 Monorepo 平台,通过智能任务编排、分布式缓存和 AI 驱动的自愈 CI,显著加速大型代码库的构建与协作。

技术简介说明

Nx(发音 "enks")是由 former Angular CLI 团队创建的开源 Monorepo 构建系统,最初由 Nrwl 公司于 2017 年推出。它的设计灵感来自 Bazel——Google 内部使用的大规模构建工具——但专注于 JavaScript/TypeScript 生态,并以开发者体验为核心。Nx 将代码仓库视为一个有向无环图(DAG),通过静态分析建立项目间的依赖关系,从而实现精准的增量构建和任务编排。

Nx 的核心价值在于"智能感知变更"。通过 project graph(项目图),Nx 能精确判断哪些项目受到代码变更的影响(affected),进而只运行必要的任务。配合本地和远程分布式缓存,团队可以跨机器、跨 CI 共享构建产物,将 CI 时间从数十分钟压缩到数秒。2025-2026 年,Nx 进一步演进为"Monorepo 平台",集成 AI Agent 能力,推出 Self-Healing CI、Agentic Migrate 等创新功能,重新定义了大规模代码库的维护方式。

Nx 不仅支持前端技术栈(React、Angular、Vue、Next.js、NestJS 等),还通过插件体系扩展到 Java(Maven/Gradle)、.NET、Rust 等多语言场景,使其成为企业级 Monorepo 的统一构建入口。

基本信息

  • 官网https://nx.dev
  • GitHubhttps://github.com/nrwl/nx
  • License:MIT
  • 最新版本:Nx 23.0(2026-06-16 发布)
  • 主要维护者/公司:Nx(原 Nrwl),核心团队包括 Victor Savkin、Jeff Cross 等前 Angular CLI 核心成员

快速上手

安装

从零创建 Nx 工作区

# 使用 npx(推荐)
npx create-nx-workspace@latest my-workspace
 
# 交互式选择预设:
# - apps       :基于应用的多项目结构
# - empty      :空工作区,手动添加项目
# - npm        :纯 npm 包管理
# - ts         :TypeScript 单体仓库

集成到已有仓库

# 在已有 package.json 的根目录运行
npx nx@latest init
 
# 会自动检测技术栈并安装对应插件

全局安装 Nx CLI

npm install -g nx
# 或
pnpm add -g nx

基础配置

工作区结构

my-workspace/
├── apps/                    # 应用项目
│   ├── web-app/
│   └── api-server/
├── libs/                    # 共享库
│   ├── ui/
│   └── utils/
├── nx.json                  # Nx 核心配置
├── package.json
├── tsconfig.base.json       # TypeScript 路径映射
└── .nx/                     # Nx 缓存目录

nx.json 核心配置

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],           // 依赖上游项目的 build
      "cache": true,                      // 启用缓存
      "inputs": ["production", "^production"],
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production"]
    },
    "lint": {
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/jest.config.ts"
    ],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "nxCloudAccessToken": "your-token-here",  // 可选:Nx Cloud 远程缓存
  "plugins": [
    {
      "plugin": "@nx/eslint/plugin",
      "options": { "targetName": "lint" }
    },
    {
      "plugin": "@nx/jest/plugin",
      "options": { "targetName": "test" }
    }
  ]
}

最小示例

生成一个 React 应用

# 添加 React 插件
nx add @nx/react
 
# 生成应用
nx g @nx/react:app apps/web-app
 
# 生成共享库
nx g @nx/react:lib libs/ui

运行任务

# 构建单个项目
nx build web-app
 
# 运行所有项目的构建(并行)
nx run-many -t build
 
# 只构建受影响的(affected)项目
nx affected -t build
 
# 可视化项目依赖图
nx graph

project.json 示例

// apps/web-app/project.json
{
  "name": "web-app",
  "sourceRoot": "apps/web-app/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web-app",
        "main": "apps/web-app/src/main.tsx",
        "tsConfig": "apps/web-app/tsconfig.app.json"
      },
      "configurations": {
        "production": { "optimization": true }
      }
    },
    "serve": {
      "executor": "@nx/webpack:dev-server",
      "options": { "buildTarget": "web-app:build" }
    },
    "test": {
      "executor": "@nx/jest:jest",
      "outputs": ["{workspaceRoot}/coverage/apps/web-app"],
      "options": { "jestConfig": "apps/web-app/jest.config.ts" }
    }
  }
}

核心概念与架构

Project Graph(项目图)

Nx 的核心是项目图——一个静态分析生成的有向无环图(DAG)。Nx 通过以下方式构建项目图:

  1. 显式依赖project.json 中的 targets.dependsOn 声明
  2. 隐式依赖:源码中的 import 语句、TypeScript 路径映射、workspace 协议引用
  3. 插件推断:通过 createNodesV2 API,插件自动从现有配置文件(如 package.jsontsconfig.jsonCargo.toml)推断项目和目标

项目图存储在 .nx/cache 中,增量更新,支持 nx graph 可视化查看。

Affected(影响分析)

Nx 通过比较 Git 历史(HEAD 与基准分支)计算变更影响范围。nx affected 命令只运行受变更影响的项目任务,是 CI 加速的关键。

# 对比 main 分支,只构建受影响的项目
nx affected -t build --base=main

分布式任务缓存

Nx 的缓存分为三层:

  1. 本地缓存~/.nx/cache.nx/cache,基于任务的输入哈希
  2. 共享文件系统缓存:挂载 NFS/SMB 等共享存储
  3. Nx Cloud 远程缓存:跨团队、跨 CI 的分布式缓存,支持任务分派

缓存键由以下因素计算:

  • 项目源码文件
  • 依赖项目的源码
  • 任务命令与配置
  • 环境变量(可配置)
  • 全局 workspace 文件

Target(目标)与 Executor(执行器)

  • Target:项目上可执行的操作,如 buildtestlint
  • Executor:执行 target 的具体逻辑,由插件提供(如 @nx/webpack:webpack

Nx 22+ 推荐使用 inferred tasks(推断任务),即插件自动从原生配置文件推断 target,无需手写 project.json

插件系统

Nx 采用插件架构,每个插件可以:

  1. 推断项目:通过 createNodesV2 从配置文件生成项目定义
  2. 提供 Executor:封装构建、测试、lint 等工具
  3. 提供 Generator:脚手架代码生成(应用、库、组件等)
  4. 定义 Migrations:版本升级时的自动转换脚本

核心特性

1. 智能任务编排与并行执行

Nx 自动分析任务依赖关系,最大化并行执行。支持 nx run-many(多项目运行)、nx affected(影响分析)、nx each(逐项目执行)等命令,并通过 targetDefaults.dependsOn 声明任务间依赖。

2. 分布式缓存(本地 + Nx Cloud)

三层缓存体系:本地磁盘、共享文件系统、Nx Cloud 远程缓存。缓存命中率通常可达 70-90%,大幅减少重复构建。Nx Cloud 还提供任务分派(Task Distribution),将任务分配到多台 CI 机器。

3. Self-Healing CI(自愈 CI)

Nx 22 引入的突破性功能。Nx Cloud 自动分析失败的 PR,利用 workspace 结构知识生成修复建议。开发者可在 UI 中审查、本地应用或直接推送修复。2026 年路线图将进一步引入 LLM 驱动的 flaky task 检测。

4. Nx Agents(AI 驱动的 CI 代理)

Nx 23 将 Nx Agents 提升为核心能力,比标准 GitHub Actions 快 4 倍、成本低 30%。通过重构的资源类和智能任务分配,自动优化 CI 流水线。配合 agentic nx migrate,AI 可自适应技术栈执行多主版本升级。

5. 影响分析(Affected Commands)

基于 Git diff 和项目图,精确识别受代码变更影响的项目。CI 中只运行受影响的任务,将大型仓库的 CI 时间从小时级压缩到分钟级。

6. 项目图可视化与治理

nx graph 提供交互式依赖图,支持按项目、文件、任务过滤。配合 Module Boundaries 规则(ESLint 插件 @nx/enforce-module-boundaries),可在 CI 中强制执行架构约束,防止循环依赖和跨层引用。

7. 代码生成(Generators)

插件提供丰富的脚手架生成器:应用、库、组件、页面、E2E 测试等。生成器自动处理配置、路径映射、tsconfig 等,确保新项目遵循 workspace 规范。

8. 多语言支持

通过插件体系扩展到多种语言和框架:

  • JavaScript/TypeScript:React、Angular、Vue、Next.js、NestJS、Node、Expo、React Native
  • Java@nx/maven@nx/gradle(实验性,CI 时间减少 59.6%)
  • .NET@nx/dotnet(GA),支持 C#、F#、VB.NET
  • Rust:通过社区插件

9. 任务沙箱(Task Sandboxing)

Nx 23 引入操作系统级别的验证,检查每个任务的读写操作是否与其声明的 inputsoutputs 匹配。防止任务写入未声明的输出导致缓存失效,确保缓存准确性。

10. Nx Release(版本发布管理)

内置版本管理工具,支持:

  • 图感知的依赖版本更新(updateDependents
  • Conventional Commits 自动版本号计算
  • Changelog 生成(支持自定义分组)
  • 多项目独立版本或统一版本
  • npm/pnpm/yarn publish

生态图

核心插件(官方维护)

插件用途
@nx/reactReact 应用与库
@nx/nextNext.js 应用
@nx/angularAngular 应用与库
@nx/vueVue 应用
@nx/nestNestJS 后端
@nx/nodeNode.js 应用
@nx/expressExpress 应用
@nx/expoReact Native (Expo)
@nx/react-nativeReact Native CLI
@nx/web纯 Web 项目
@nx/jsTypeScript/JavaScript 库
@nx/webpackWebpack 构建
@nx/rspackRspack 构建
@nx/esbuildesbuild 构建
@nx/viteVite 构建
@nx/jestJest 测试
@nx/vitestVitest 测试
@nx/playwrightPlaywright E2E
@nx/cypressCypress E2E
@nx/eslintESLint 配置
@nx/prettierPrettier 格式化
@nx/storybookStorybook 集成
@nx/module-federation模块联邦
@nx/mavenMaven 项目(实验性)
@nx/gradleGradle 项目(实验性)
@nx/dotnet.NET 项目(GA)

社区插件

插件用途
@nx-go/nx-goGo 语言支持
@nxrs/cargoRust/Cargo 支持
@nxrocks/nx-flutterFlutter 支持
@nxrocks/nx-spring-bootSpring Boot 支持
@nxpy/djangoDjango/Python 支持
@nx-extend/*各种部署与工具扩展

关键依赖

  • yargs:CLI 参数解析
  • chalk:终端颜色输出
  • enquirer:交互式 CLI 提示
  • tar:缓存打包
  • ignore:.gitignore 解析
  • semver:语义化版本处理

Nx Cloud 生态

  • Nx Cloud App:GitHub/GitLab 集成,PR 评论缓存命中、任务分布状态
  • Nx Console:VS Code、Cursor、JetBrains IDE 插件,提供可视化项目图、任务运行、迁移 UI
  • Nx MCP:Model Context Protocol 支持,让 AI Agent 直接操作 Nx workspace

相关工具

  • Lerna:Nx 团队同时维护,专注于 npm 包发布与版本管理,可与 Nx 配合使用
  • Nrwl Accordion:企业级 Nx 工作区高级支持与培训

适用场景

1. 大型前端 Monorepo

管理数十到数百个前端项目(React/Angular/Vue)的统一工作区。Nx 的影响分析和缓存机制可将 CI 时间从小时级压缩到分钟级,项目图和模块边界规则保障架构一致性。

2. 全栈 TypeScript 仓库

前后端共享类型、工具函数、验证逻辑。Nx 的 TypeScript 路径映射和依赖追踪确保跨项目变更的即时传播,避免版本不一致。

3. 多团队企业级 Monorepo

数百名开发者协作的大型代码库。Nx Cloud 的远程缓存、任务分布、Affected 分析是核心能力。Module Boundaries 规则强制执行团队间的架构约束,防止"大泥球"。

4. 微前端架构(Module Federation)

Nx 对 Webpack Module Federation 和 Rspack Module Federation 提供一等支持。@nx/module-federation 插件自动配置 host/remote 关系、类型安全和开发服务器联调。

5. 多语言/多框架混合仓库

需要同时管理 JavaScript/TypeScript、Java、.NET、Rust 等多种语言的仓库。Nx 的插件体系和 Project Graph 提供统一的任务编排入口。

6. 库开发与发布(Component Library)

开发多个 npm 包或内部组件库。Nx 的 Project Graph 追踪包间依赖,nx release 处理版本发布和 changelog 生成,updateDependents 自动更新下游包。

7. 渐进式迁移

从 Lerna、Yarn Workspaces、pnpm Workspaces 或 Turborepo 迁移。nx init 可集成到现有仓库,不强制立即改造结构,逐步采用 Nx 特性。

开发与工程化

开发流程

本地开发

# 启动开发服务器
nx serve web-app
 
# 多项目并行开发
nx run-many -t serve -p web-app api-server
 
# 监听模式(文件变更自动重跑)
nx test --watch

代码生成

# 生成 React 组件
nx g @nx/react:component libs/ui/src/lib/Button
 
# 生成 NestJS 模块
nx g @nx/nest:module libs/api/src/lib/users
 
# 生成 E2E 测试
nx g @nx/playwright:configuration apps/web-app

构建部署

构建产物

# 生产构建
nx build web-app --configuration=production
 
# 输出到 dist/apps/web-app

Docker 部署

FROM node:20-alpine AS builder
WORKDIR /app
COPY . .
RUN pnpm install --frozen-lockfile
RUN pnpm nx build web-app --configuration=production
 
FROM node:20-alpine
COPY --from=builder /app/dist/apps/web-app ./app
CMD ["node", "app/main.js"]

工程化最佳实践

1. 项目结构规范

  • apps/:可部署的应用,不包含被其他项目引用的代码
  • libs/:共享库,按领域划分(libs/authlibs/uilibs/utils
  • 每个项目独立 project.json,避免在 nx.json 中硬编码

2. 缓存配置

// nx.json
{
  "targetDefaults": {
    "build": {
      "inputs": ["production", "^production"],
      "outputs": ["{projectRoot}/dist"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production"],
      "cache": true
    }
  }
}

3. Module Boundaries

// .eslintrc.json
{
  "rules": {
    "@nx/enforce-module-boundaries": [
      "error",
      {
        "enforceBuildableLibDependency": true,
        "allow": [],
        "depConstraints": [
          {
            "sourceTag": "scope:shared",
            "onlyDependOnLibsWithTags": ["scope:shared"]
          },
          {
            "sourceTag": "scope:web",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:web"]
          },
          {
            "sourceTag": "scope:api",
            "onlyDependOnLibsWithTags": ["scope:shared", "scope:api"]
          }
        ]
      }
    ]
  }
}

CI/CD 集成

GitHub Actions

name: CI
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Nx affected 需要完整 Git 历史
 
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
 
      - run: pnpm install --frozen-lockfile
 
      # 使用 Nx Cloud 分派任务
      - uses: nrwl/nx-set-shas@v4
 
      - run: pnpm nx affected -t lint test build
        env:
          NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

关键 CI 优化

  1. nrwl/nx-set-shas:自动计算正确的 --base--head,确保 affected 分析准确
  2. Nx Cloud 任务分布:将 affected 任务自动分派到多台 runner,进一步加速
  3. Self-Healing CI:Nx Cloud 自动修复 flaky 测试和配置错误
  4. Task Sandboxing(Nx 23):CI 中验证任务的输入/输出声明,防止缓存污染

性能与安全

性能特点

特性说明
原生 TypeScript 加载Nx 23 默认启用,无需编译 .ts 配置文件,启动更快
V8 编译缓存缓存已编译的 JS 模块,重复执行时显著减少启动时间
Project Graph 增量更新只重新分析变更文件,不重建整个图
Composite Mode(图可视化)大型仓库(数千项目)下防止浏览器崩溃
并行任务执行自动最大化并行度,受 --parallel--max-parallel 控制
分布式缓存Nx Cloud 跨 CI 共享缓存,缓存命中率 70-90%
Gradle 优化Nx 22 的 Gradle 插件将 Spring Boot CI 从 1h44m 减少到 42m(59.6%)

优化建议

  1. 合理配置 inputsoutputs:避免将无关文件纳入缓存键,提高缓存命中率
  2. 使用 nx-cloud 远程缓存:团队规模 >5 人时收益显著
  3. 避免 nx run-many --all:优先使用 nx affected 只运行受影响任务
  4. 拆分过大项目:单个项目超过 500 个文件时考虑按领域拆分
  5. 使用 --parallel--max-parallel:根据 CI 机器 CPU 核心数调整
  6. 启用 Task Sandboxing:确保任务输入/输出声明准确,防止缓存失效

安全注意事项

  1. Nx Cloud 访问令牌NX_CLOUD_ACCESS_TOKEN 应存储在 CI 密钥管理中,不提交到仓库
  2. 依赖审计:定期运行 pnpm audit / npm audit,Nx 本身不替代包安全扫描
  3. Module Boundaries:通过 ESLint 规则防止敏感代码被低权限项目引用
  4. 代码生成安全:Generator 模板应审查,避免引入不安全的默认配置
  5. 任务沙箱:Nx 23 的 Task Sandboxing 防止任务写入未声明路径,减少构建污染

已知性能瓶颈

  1. 超大仓库的 Project Graph 构建:数千项目的首次图构建可能需要数十秒(增量更新后显著改善)
  2. Windows 下的文件监听:大仓库下 nx serve --watch 可能遇到文件监听延迟,建议启用 NX_USE_WATCHMAN=1
  3. Nx Cloud 网络延迟:跨地域团队缓存上传/下载可能受网络影响,Nx Cloud 提供多区域部署
  4. 缓存膨胀:长期不清理本地缓存可能占用大量磁盘空间,建议定期清理 ~/.nx/cache

技术对比

Nx vs Turborepo

维度NxTurborepo
定位完整的 Monorepo 平台轻量级构建系统
语言JavaScript/TypeScript + 插件扩展到 Java/.NET/Rust专注 JavaScript/TypeScript
项目图静态分析生成完整 DAG,支持 nx graph 可视化基于 package.json 依赖推断,无独立可视化
缓存本地 + 共享文件系统 + Nx Cloud 远程缓存本地 + Vercel Remote Cache
代码生成丰富的 Generator 生态(应用、库、组件)无内置代码生成
架构治理@nx/enforce-module-boundaries ESLint 规则无内置架构治理
AI 能力Nx Agents、Self-Healing CI、Agentic Migrate(2026)无 AI 集成
学习曲线中高(概念多:project graph、targets、executors、plugins)低(配置简单,turbo.json 即可)
启动速度较慢(需分析项目图)快(Rust 实现,轻量)
适用规模大型仓库(100+ 项目)优势明显中小型仓库(10-50 项目)更合适
维护者Nx(Nrwl)Vercel
LicenseMITMIT

选择建议

  • Nx:大型 Monorepo、多语言、需要架构治理、AI 驱动的 CI、企业级支持
  • Turborepo:中小型 JS/TS 仓库、追求零配置、已使用 Vercel 部署

Nx vs Bazel

维度NxBazel
定位JS/TS 友好的 Monorepo 平台通用大规模构建系统
学习曲线中等(JS/TS 开发者友好)极高(Starlark 语言、Bazel 概念体系)
配置复杂度nx.json + project.json(JSON 格式)BUILD.bazel + WORKSPACE(Starlark 语言)
生态JS/TS 插件丰富,开箱即用需自建规则或依赖社区规则
远程缓存Nx Cloud 开箱即用需自建或配置 BuildBuddy/Bazel Remote
多语言通过插件扩展,非核心强项核心设计目标,多语言支持完善
适用规模中大型 JS/TS 仓库超大型多语言仓库(Google 级别)
社区活跃的 JS 生态社区大型企业级用户

选择建议

  • Nx:以 JS/TS 为主的仓库,团队无 Bazel 经验
  • Bazel:多语言超大仓库、已有 Bazel 基础设施、需要极致定制化

Nx vs Lerna

维度NxLerna
定位构建系统 + 任务编排npm 包发布与版本管理
关系Lerna 由 Nx 团队维护,两者互补可独立使用,也可与 Nx 配合
任务执行强大的并行、缓存、affected基础的任务执行
版本发布nx release 内置核心功能,Conventional Commits
适用场景全栈 Monorepo纯 npm 包 Monorepo

选择建议

  • Nx:需要完整构建系统
  • Lerna:纯 npm 包发布,无需复杂构建
  • 两者配合:Nx 管理构建,Lerna 管理发布

最佳实践

生产环境最佳实践

1. 渐进式采用

# 不要一开始就强制所有项目迁移
npx nx@latest init
 
# 先让现有项目正常运行
# 逐步添加 Nx 特性:缓存 → affected → 代码生成 → Module Boundaries

2. 合理的项目拆分

  • 按领域拆分libs/authlibs/paymentlibs/ui,而非按技术类型 libs/componentslibs/services
  • 库的粒度:一个库应服务于一个明确的领域,避免"万能库"
  • 应用与库分离apps/ 只包含可部署应用,libs/ 包含共享代码

3. 缓存策略

// nx.json - 精细化缓存配置
{
  "targetDefaults": {
    "build": {
      "inputs": [
        "production",
        "^production",
        { "env": "NODE_ENV" }  // 环境变量纳入缓存键
      ],
      "cache": true
    },
    "dev": {
      "cache": false  // 开发服务器不缓存
    }
  }
}

4. CI 优化

  • 使用 nx affected:只运行受影响任务
  • 启用 Nx Cloud:远程缓存 + 任务分布
  • 设置 --parallel:根据 CI 机器核心数调整(通常 --parallel=3--max-parallel=3
  • Git fetch depth:使用 nrwl/nx-set-shas 确保完整的 Git 历史

5. 架构治理

  • Module Boundaries:通过 ESLint 规则强制执行团队间的依赖约束
  • Project Graph 审查:定期使用 nx graph 检查依赖关系,防止循环依赖
  • Dep Graph CI Check:在 CI 中运行 nx graph --file=graph.json 并检查架构违规

常见陷阱

1. 缓存未命中

问题:缓存命中率低,CI 加速效果不明显。

原因与解决

  • inputs 配置过宽:排除测试文件、文档等无关文件
  • 全局文件变更导致全量重建:使用 namedInputs.sharedGlobals 精确控制
  • 环境变量未纳入缓存键:在 inputs 中添加 { "env": "VAR_NAME" }

2. Project Graph 构建慢

问题:首次 nx graph 或 CI 中图构建时间过长。

原因与解决

  • 仓库过大:拆分为多个 workspace 或使用 Nx Cloud 分布式执行
  • 插件推断效率低:检查插件版本,使用 NX_DAEMON=false 调试
  • 文件监听问题:Windows 下启用 NX_USE_WATCHMAN=1

3. 循环依赖

问题nx graph 显示循环依赖,nx build 报错。

解决

  • 重构代码,提取共享逻辑到独立库
  • 使用 @nx/enforce-module-boundaries 在 CI 中预防
  • 临时使用 implicitDependencies 声明合法循环(不推荐)

4. 迁移冲突

问题nx migrate 后项目无法构建。

预防

  • 迁移前提交所有变更,创建备份分支
  • 分步迁移:nx migrate next → 测试 → 再迁移
  • 使用 Nx Console 的 Migrate UI 可视化审查变更

推荐模式

1. 库的可见性控制

// libs/ui/project.json
{
  "name": "ui",
  "sourceRoot": "libs/ui/src",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "options": {
        "outputPath": "dist/libs/ui"
      }
    }
  }
}

配合 tsconfig.base.json 路径映射:

{
  "compilerOptions": {
    "paths": {
      "@my-org/ui": ["libs/ui/src/index.ts"],
      "@my-org/utils": ["libs/utils/src/index.ts"]
    }
  }
}

2. 共享环境配置

// tools/workspace/src/lib/env.ts
export const getWorkspaceEnv = () => {
  return {
    isCI: process.env.CI === 'true',
    isNxCloud: !!process.env.NX_CLOUD_ACCESS_TOKEN,
    workspaceRoot: process.env.NX_WORKSPACE_ROOT || process.cwd(),
  };
};

3. 自定义 Executor

// tools/executors/custom-build/src/executor.ts
import { ExecutorContext } from 'nx/src/config/misc-interfaces';
 
export interface CustomBuildOptions {
  outputPath: string;
  main: string;
}
 
export default async function customBuildExecutor(
  options: CustomBuildOptions,
  context: ExecutorContext
) {
  console.log(`Building ${context.projectName} to ${options.outputPath}`);
  // 自定义构建逻辑
  return { success: true };
}

技术局限与边界

已知限制

  1. 学习曲线:概念体系复杂(Project Graph、Targets、Executors、Plugins、Inferred Tasks、Named Inputs),新手需 1-2 周适应
  2. JavaScript/TypeScript 偏重:虽然通过插件扩展到多语言,但核心优化和最佳实践仍围绕 JS/TS 生态
  3. Windows 支持:部分功能(如文件监听、Task Sandboxing)在 Windows 上存在已知问题或性能差异
  4. 插件质量不均:官方插件维护良好,但社区插件可能缺乏长期维护,升级时需注意兼容性
  5. Nx Cloud 依赖:远程缓存和高级 CI 功能依赖 Nx Cloud 服务,私有部署需企业版授权
  6. 大仓库的图构建:数千项目的首次 Project Graph 构建可能较慢(增量更新后改善)
  7. 版本升级成本:主版本升级可能包含破坏性变更(如 Nx 23 移除大量弃用 API),需仔细规划迁移

不适用场景

  1. 单项目仓库:Nx 的价值在于多项目管理,单项目使用 Nx 会增加不必要的复杂度
  2. 极小型 Monorepo(<5 包):pnpm workspaces 或 Yarn workspaces 已足够,Nx 的 overhead 不划算
  3. 非 JavaScript 为主的多语言仓库:Bazel 或 Pants 更适合以 Java/C++/Go 为主的超大型多语言仓库
  4. 快速原型/实验项目:Nx 的配置和规范适合长期项目,短期原型建议使用更轻量的工具
  5. 已深度绑定其他构建系统:如已使用 Bazel/Gradle 且运行良好,迁移到 Nx 的成本可能高于收益

权衡取舍

选择 Nx 的收益需付出的代价
强大的缓存和 CI 加速学习曲线陡峭,概念多
完整的项目图和依赖分析首次图构建耗时
丰富的代码生成器生成器模板可能不符合团队习惯
架构治理(Module Boundaries)需要前期设计约束规则
AI 驱动的自愈 CI(Nx 23+)依赖 Nx Cloud 服务
多语言扩展能力非 JS 语言的插件成熟度较低

迁移注意事项

从 Lerna 迁移

# Lerna 由 Nx 团队维护,迁移路径清晰
npx nx@latest init
# Nx 会自动检测 Lerna 配置并提供迁移建议

从 Turborepo 迁移

  1. turbo.json 中的 pipeline 对应 nx.jsontargetDefaults
  2. Turborepo 的 // 依赖语法对应 Nx 的 ^targetName
  3. 缓存配置基本兼容,但 Nx 的 inputs 更精细
  4. 无自动迁移工具,需手动转换配置

从 Yarn/PNPM Workspaces 迁移

  1. nx init 会自动检测 workspace 配置
  2. 现有 package.json 中的 scripts 可通过插件推断为 Nx targets
  3. 逐步添加 Nx 特性,无需一次性重构

通用迁移建议

  • 先在新分支试验git checkout -b nx-migration
  • 分阶段采用:缓存 → affected → 代码生成 → Module Boundaries → Nx Cloud
  • 保持现有 scripts:Nx 兼容 package.json scripts,无需立即删除
  • 测试 CI 流水线:迁移后先在 CI 中验证 affected 分析的准确性

学习资源

官方文档

教程

社区资源

书籍与课程

  • 《Effective Monorepos with Nx》:Nx 官方电子书
  • 《Monorepo Development with Nx》:Packt Publishing
  • Egghead.io Nx Courseshttps://egghead.io/q?q=nx
  • Frontend Masters:部分课程涵盖 Nx 实践

2026 年现状

最新版本

Nx 23.0(2026-06-16 发布)是当前的最新主版本,主要更新包括:

  • Nx Agents 性能飞跃:比标准 GitHub Actions 快 4 倍、成本低 30%,得益于重构的资源类和智能任务分配
  • Agentic nx migrate:AI 驱动的多主版本升级,自适应技术栈
  • Task Sandboxing:OS 级别的任务输入/输出验证,确保缓存准确性
  • @nx/dotnet GA:.NET 项目一等公民支持
  • 原生 TypeScript 加载 + V8 编译缓存:默认启用,启动更快
  • 破坏性变更:移除大量长期弃用的 API 和生成器

发展趋势

根据 Nx 2026 Roadmap(2026-02-04 发布),核心发展方向包括:

  1. AI Agent 深化

    • 更强大的 Self-Healing CI,自动修复更多类型的失败
    • LLM 驱动的 flaky task 检测与处理
    • Agentic 多步骤任务编排(跨多个 PR 的协调修复)
  2. 核心性能优化

    • 核心正迁移到编译语言(Rust),进一步减少包大小和提升速度
    • Project Graph 构建速度持续优化
    • Windows 平台支持完善
  3. 多语言扩展

    • @nx/dotnet 已达到 GA,@nx/maven@nx/gradle 处于实验阶段
    • 更多语言插件计划中
  4. 开发者体验

    • Nx Console 与 IDE 深度集成(VS Code、Cursor、JetBrains)
    • MCP(Model Context Protocol)支持,让 AI Agent 直接操作 workspace
    • 简化配置,减少 project.json 的手动维护

社区活跃度

  • GitHub Stars:~25k+(持续增长)
  • npm 周下载量nx 包约 500 万+/周
  • 贡献者:1000+ 核心贡献者
  • Discord 活跃度:高,官方团队响应及时
  • 企业用户:包括 Microsoft、American Airlines、Cisco、Dynatrace 等

未来路线图

  • Nx 24(预计 2026 Q4)

    • 进一步增强的 AI Agent 能力
    • 更完善的 Task Sandboxing
    • 更多语言插件 GA
    • Nx Cloud 私有部署选项扩展
  • 长期愿景

    • Nx 作为"Monorepo 操作系统",统一管理构建、测试、部署、AI 协作
    • 与主流 AI 编码助手(Cursor、GitHub Copilot、Claude)深度集成
    • 进一步降低学习曲线,实现"零配置"采用

参考来源