Nx CLI 使用指南

Nx 是 NextUI 框架的命令行工具，提供项目管理、代码检查、文档查看、AI 辅助等功能。

目录

• 安装
• 快速开始
• 配置文件
• 命令参考
  • nx build
  • nx pack
  • nx push
  • nx run
  • nx test
  • nx doc
  • nx check
  • nx lint
  • nx ai
  • nx upgrade
• 项目类型
• 规则配置
• AI 配置

安装

Nx CLI 作为 .NET 全局工具安装：

dotnet tool install -g Nx

更新到最新版本：

dotnet tool update -g Nx

快速开始

在项目根目录创建 nx.json 配置文件：

{
  "name": "MyProject",
  "projectType": "nextui-app"
}

然后运行常用命令：

# 构建项目
nx build

# 运行项目
nx run

# 运行测试
nx test

# 检查项目健康状况
nx check

# 代码规范检查
nx lint

配置文件

Nx 使用 nx.json 作为项目配置文件，位于项目根目录。

基础配置

{
  "name": "MyProject",
  "projectType": "nextui-app",
  "description": "项目描述"
}

完整配置示例

{
  "name": "MyProject",
  "projectType": "nextui-app",

  "ai": {
    "provider": "claude-code",
    "claudeCode": {
      "path": "claude",
      "model": "sonnet"
    },
    "claudeApi": {
      "apiKeyEnv": "ANTHROPIC_API_KEY",
      "model": "claude-sonnet-4-20250514"
    }
  },

  "lint": {
    "rulesFile": "lint-rules.json",
    "exclude": ["**/bin/**", "**/obj/**", "**/generated/**"],
    "rules": {
      "NX001": { "enabled": false },
      "NX007": { "severity": "warning" }
    }
  },

  "docs": {
    "directories": ["docs", "api-docs"],
    "include": ["README.md", "CHANGELOG.md", "CONTRIBUTING.md"]
  },

  "tests": {
    "directory": "tests",
    "pattern": "*.Tests.csproj"
  },

  "nuget": {
    "source": "https://api.nuget.org/v3/index.json",
    "apiKeyEnv": "NUGET_API_KEY",
    "privateSource": "https://my.nuget.server/",
    "privateApiKeyEnv": "PRIVATE_NUGET_KEY"
  },

  "nextui": {
    "version": "1.3.9",
    "features": ["blazor", "maui"]
  }
}

命令参考

nx build

构建项目或解决方案。

# 构建当前项目
nx build

# 指定配置
nx build -c Release

# 构建解决方案
nx build -s NextUI.sln

# 详细输出
nx build -v

选项：

nx pack

打包 NuGet 包。

# 打包当前项目
nx pack

# 指定版本
nx pack --version 1.0.0

# 发布版本
nx pack -c Release

选项：

nx push

推送 NuGet 包到服务器。

# 推送包
nx push MyPackage.1.0.0.nupkg

# 指定源
nx push MyPackage.nupkg --source https://api.nuget.org/v3/index.json

选项：

nx run

运行项目。

# 运行默认项目
nx run

# 运行指定项目
nx run workbench

# 运行 WASM 项目
nx run --wasm

# 在浏览器中打开
nx run -b

选项：

nx test

运行测试。

# 运行所有测试
nx test

# 运行指定项目
nx test MyProject.Tests

# 过滤测试
nx test --filter "Category=Unit"

# 详细输出
nx test -v

选项：

nx doc

查看文档。默认显示 NextUI 框架文档，使用 -l 查看当前项目文档。

列出文档

# 列出 NextUI 框架文档（默认）
nx doc list

# 列出当前项目文档
nx doc list -l
nx doc list --local

查看文档

# 在终端查看 NextUI 文档
nx doc view SxButton

# 在终端查看当前项目文档
nx doc view guide -l

在浏览器中查看

# 打开 NextUI 文档索引页（默认）
nx doc open

# 打开当前项目文档索引页
nx doc open -l

# 打开指定的 NextUI 组件文档
nx doc open SxButton

# 打开指定的本地文档
nx doc open guide -l

打开索引页时，会生成带左侧导航的 HTML 页面：

• 左侧显示按分类整理的文档目录
• 右侧显示文档内容
• 支持深色模式
• 响应式设计，支持移动端

缓存管理

文档会缓存到 ~/.nx/doc-cache/{版本}/ 目录：

• NextUI 文档：~/.nx/doc-cache/{版本}/_nextui_/
• 项目文档：~/.nx/doc-cache/{版本}/{项目名}/

# 查看缓存信息
nx doc cache

# 清除 NextUI 文档缓存
nx doc clear

# 清除当前项目文档缓存
nx doc clear -l

# 清除所有版本的缓存
nx doc clear --all

缓存按 CLI 版本区分，升级 CLI 后会自动使用新缓存。NextUI 文档打包在 CLI 中，无需网络连接即可查看。

nx check

检查项目健康状况。

# 运行所有检查
nx check

# 运行特定检查
nx check --id NX-SDK-001

# 详细输出
nx check -v

选项：

内置检查器：

nx lint

代码规范检查。

# 运行所有规则
nx lint

# 运行并自动修复
nx lint --fix

# 只运行特定规则
nx lint --rules NX007

# 禁用特定规则
nx lint --disable NX001,NX003

# 详细输出
nx lint -v

选项：

内置规则：

nx ai

AI 辅助功能。

检查代码

# AI 分析代码问题
nx ai check

# 指定文件
nx ai check --file src/Components/Button.razor

# 使用特定 provider
nx ai check --provider claude-api

解释代码

# 解释代码
nx ai explain --file src/Complex.cs

代码审查

# 审查代码
nx ai review --file src/NewFeature.razor

修复代码

# AI 建议修复
nx ai fix --file src/Buggy.cs

# 应用修复
nx ai fix --file src/Buggy.cs --apply

选项：

nx upgrade

升级 NextUI 包版本。

# 检查可升级的包
nx upgrade

# 升级到指定版本
nx upgrade --version 1.4.0

# 预览升级
nx upgrade --dry-run

选项：

项目类型

Nx 自动检测项目类型，也可在 nx.json 中显式指定：

{
  "projectType": "nextui-app"
}

自动检测规则：

• NextUI Framework: 存在 src/NextUI.Blazor 目录
• NextUI App: 项目引用了 NextUI.* 包
• Generic: 其他情况

规则配置

在 nx.json 中配置

{
  "lint": {
    "rules": {
      "NX001": {
        "enabled": false
      },
      "NX007": {
        "severity": "warning",
        "options": {
          "allowedColors": ["transparent", "inherit", "currentColor"]
        }
      }
    }
  }
}

使用独立规则文件

{
  "lint": {
    "rulesFile": "lint-rules.json"
  }
}

lint-rules.json:

{
  "NX001": { "enabled": true },
  "NX003": { "enabled": true },
  "NX007": { "severity": "error" }
}

排除文件

{
  "lint": {
    "exclude": [
      "**/bin/**",
      "**/obj/**",
      "**/wwwroot/lib/**",
      "**/Generated/**"
    ]
  }
}

AI 配置

使用 Claude Code (推荐)

需要安装 Claude Code 并完成订阅。

{
  "ai": {
    "provider": "claude-code",
    "claudeCode": {
      "path": "claude",
      "model": "sonnet"
    }
  }
}

模型选项：

• sonnet - Claude Sonnet (默认，平衡速度和质量)
• opus - Claude Opus (最高质量)
• haiku - Claude Haiku (最快速度)

使用 Claude API

需要设置 API 密钥环境变量。

{
  "ai": {
    "provider": "claude-api",
    "claudeApi": {
      "apiKeyEnv": "ANTHROPIC_API_KEY",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

设置环境变量：

export ANTHROPIC_API_KEY="your-api-key"

提供者优先级

当不指定 provider 时，Nx 按以下优先级选择：

1. Claude Code (优先级 100) - 如果已安装且可用
2. Claude API (优先级 90) - 如果配置了 API 密钥

环境变量

常见问题

Q: 如何忽略特定文件的 lint 检查？

在文件开头添加注释：

@* nx-lint-disable NX007 *@

或在 nx.json 的 exclude 配置中添加文件模式。

Q: Claude Code 无法使用？

确保：

1. 已安装 Claude Code CLI
2. 已完成 Claude 订阅
3. claude 命令在 PATH 中可用

可使用 claude --version 验证安装。

Q: 如何添加自定义 lint 规则？

目前支持通过配置文件调整内置规则。自定义规则开发请参考 CLI 设计文档。

Q: 升级命令无法获取最新版本？

检查：

1. NuGet 源配置是否正确
2. 网络连接是否正常
3. 尝试添加 --include-prerelease 包含预发布版本

更多信息

• CLI 设计文档
• NextUI 框架文档
• 问题反馈