nx-workspace

Nx 工作区探索

此技能提供对 Nx 工作区的只读探索。可用它了解工作区结构、项目配置、可用目标和依赖项。

请注意，如果没有全局安装 nx，可能需要在命令前加上 npx/pnpx/yarn。检查锁文件以确定所使用的包管理器。

列出项目

使用 nx show projects 列出工作区中的项目。

项目筛选语法（-p/--projects）适用于许多 Nx 命令，包括 nx run-many、nx release、nx show projects 等。筛选条件支持指定名称、glob 模式、标签引用（例如 tag:name）、目录和否定条件（例如 !project-name）。

# List all projects
nx show projects

# Filter by pattern (glob)
nx show projects --projects "apps/*"
nx show projects --projects "shared-*"

# Filter by tag
nx show projects --projects "tag:publishable"
nx show projects -p 'tag:publishable,!tag:internal'

# Filter by target (projects that have a specific target)
nx show projects --withTarget build

# Combine filters
nx show projects --type lib --withTarget test
nx show projects --affected --exclude="*-e2e"
nx show projects -p "tag:scope:client,packages/*"

# Negate patterns
nx show projects -p '!tag:private'
nx show projects -p '!*-e2e'

# Output as JSON
nx show projects --json

项目配置

使用 nx show project <name> --json 获取项目完整的解析后配置。

重要：不要直接读取 project.json——它只包含部分配置。nx show project --json 命令会返回完整的解析后配置，包括由插件推断出的目标。

你可以阅读 node_modules/nx/schemas/project-schema.json 中的完整项目架构，了解 nx 项目配置选项。

# Get full project configuration
nx show project my-app --json

# Extract specific parts from the JSON
nx show project my-app --json | jq '.targets'
nx show project my-app --json | jq '.targets.build'
nx show project my-app --json | jq '.targets | keys'


# Check project metadata
nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'

目标信息

目标定义了可以在项目上运行哪些任务。

# List all targets for a project
nx show project my-app --json | jq '.targets | keys'

# Get full target configuration
nx show project my-app --json | jq '.targets.build'

# Check target executor/command
nx show project my-app --json | jq '.targets.build.executor'
nx show project my-app --json | jq '.targets.build.command'

# View target options
nx show project my-app --json | jq '.targets.build.options'

# Check target inputs/outputs (for caching)
nx show project my-app --json | jq '.targets.build.inputs'
nx show project my-app --json | jq '.targets.build.outputs'

# Find projects with a specific target
nx show projects --withTarget serve
nx show projects --withTarget e2e

工作区配置

直接读取 nx.json 以查看工作区级别的配置。 你可以阅读 node_modules/nx/schemas/nx-schema.json 中的完整项目架构，了解 nx 项目配置选项。

# Read the full nx.json
cat nx.json

# Or use jq for specific sections
cat nx.json | jq '.targetDefaults'
cat nx.json | jq '.namedInputs'
cat nx.json | jq '.plugins'
cat nx.json | jq '.generators'

nx.json 的关键部分：

• targetDefaults - 应用于所有同名目标的默认配置
• namedInputs - 可复用的输入定义，用于缓存
• plugins - Nx 插件及其配置
• ……以及更多内容，详情请阅读架构文件或 nx.json

受影响的项目

如果用户询问受影响的项目，请阅读受影响项目参考，了解详细命令和示例。

常见探索模式

“这个工作区里有什么？”

nx show projects
nx show projects --type app
nx show projects --type lib

“如何构建/测试/检查项目 X？”

nx show project X --json | jq '.targets | keys'
nx show project X --json | jq '.targets.build'

“哪些项目依赖库 Y？”

# Use the project graph to find dependents
nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key'

以编程方式获取答案

处理 nx CLI 结果时，请使用命令行工具以编程方式计算答案，而不是手动计数或解析输出。始终使用 --json 标志获取结构化输出，以便使用 jq、grep 或本地安装的其他工具进行处理。

列出项目

nx show projects --json

示例输出：

["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"]

常见操作：

# Count projects
nx show projects --json | jq 'length'

# Filter by pattern
nx show projects --json | jq '.[] | select(startswith("shared-"))'

# Get affected projects as array
nx show projects --affected --json | jq '.'

项目详情

nx show project my-app --json

示例输出：

{
  "root": "apps/my-app",
  "name": "my-app",
  "sourceRoot": "apps/my-app/src",
  "projectType": "application",
  "tags": ["type:app", "scope:client"],
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "options": { "outputPath": "dist/apps/my-app" }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": { "buildTarget": "my-app:build" }
    },
    "test": {
      "executor": "@nx/vite:test",
      "options": {}
    }
  },
  "implicitDependencies": []
}

常见操作：

# Get target names
nx show project my-app --json | jq '.targets | keys'

# Get specific target config
nx show project my-app --json | jq '.targets.build'

# Get tags
nx show project my-app --json | jq '.tags'

# Get project root
nx show project my-app --json | jq -r '.root'

项目图

nx graph --print

示例输出：

{
  "graph": {
    "nodes": {
      "my-app": {
        "name": "my-app",
        "type": "app",
        "data": { "root": "apps/my-app", "tags": ["type:app"] }
      },
      "shared-ui": {
        "name": "shared-ui",
        "type": "lib",
        "data": { "root": "libs/shared-ui", "tags": ["type:ui"] }
      }
    },
    "dependencies": {
      "my-app": [{ "source": "my-app", "target": "shared-ui", "type": "static" }],
      "shared-ui": []
    }
  }
}

常见操作：

# Get all project names from graph
nx graph --print | jq '.graph.nodes | keys'

# Find dependencies of a project
nx graph --print | jq '.graph.dependencies["my-app"]'

# Find projects that depend on a library
nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key'

故障排除

“找不到任务 X:target 的配置”

# Check what targets exist on the project
nx show project X --json | jq '.targets | keys'

# Check if any projects have that target
nx show projects --withTarget target

“工作区不同步”

nx sync
nx reset  # if sync doesn't fix stale cache