工作区

当您使用 @aws/nx-plugin 创建新工作区时，预设生成器会设置一个 Nx monorepo，并为在 AWS 上构建提供合理的默认配置。

创建工作区

创建工作区@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

构建你的命令8

workspace必需

iac

cdkterraform

containers

inferdockerfinch

gitSecrets

true

mcp

true

module

esmcjs

catalog

true

preferInstallDependencies

true

选项

生成器选项7 个选项

iacenum默认值: cdk

首选的 IaC 提供商。

cdkterraform

containersenum默认值: infer

用于构建/推送/登录的容器引擎。'infer' 会在已安装 docker 时选择 docker，否则选择 finch（当两者都未安装时回退到 docker）。

inferdockerfinch

gitSecretsboolean默认值: true

是否配置 git-secrets 以防止提交 AWS 凭证。

mcpboolean默认值: true

是否配置 Nx Plugin for AWS MCP server 以供编码代理使用。

moduleenum默认值: esm

生成的 TypeScript 代码和配置的模块格式。

esmcjs

catalogboolean默认值: true

生成器是否在包管理器的目录（pnpm/yarn/bun）中记录依赖版本，保持版本的单一数据源。当设置为 false 时，依赖项将直接写入每个项目的 package.json，保持版本一致性将由您负责。

preferInstallDependenciesboolean默认值: true

是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

工作区结构

• 文件夹packages/ Your projects live here

  • …
• package.json Root package.json for your monorepo
• nx.json Nx configuration (common targets, sync generators, caching)
• tsconfig.base.json Root TypeScript configuration
• biome.json Biome configuration for linting and formatting
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• 文件夹.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• .gitallowed Patterns git-secrets treats as false positives
• 文件夹.husky/ Git hooks

  • …
• .mcp.json Nx Plugin for AWS MCP server configuration for Claude Code
• .cursor/mcp.json …and for Cursor
• .kiro/settings/mcp.json …and for Kiro
• .gemini/settings.json …and for Gemini CLI
• .vscode/mcp.json …and for GitHub Copilot
• .codex/config.toml …and for OpenAI Codex

Nx

Nx 是一个用于 monorepo 的语言无关构建系统，管理用任何编程语言编写的项目之间的依赖关系以及构建它们的任务。您可以在 Nx 网站上了解更多信息。

项目

Nx monorepo 由一个或多个项目组成，每个项目都有一个 project.json 文件。project.json 定义了项目的任务，称为 targets，它们定义了项目如何构建、本地运行、测试等。它还定义了项目内部或跨项目的目标之间的依赖关系。

例如，project.json 可能定义一个 build 目标，该目标依赖于所有上游项目首先被构建：

packages/my-project/project.json

{
  "name": "@my-workspace/my-project",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"]
    },
    "test": {
      "command": "vitest run"
    }
  }
}

提示

对于 Nx Plugin for AWS 不直接支持的语言项目，您通常可以在 Nx Plugin Registry 中找到一个生成器来帮助。然而，将任何语言的项目添加到您的 monorepo 中都很简单——只需添加一个 project.json 文件并定义其 build 目标来运行该语言项目的特定构建命令。

有关如何设置 TypeScript 和 Python 项目的详细信息，请参阅 ts#project 和 py#project 生成器指南。

缓存

Nx 缓存先前执行的目标的输出，并在输入未更改时重放它们。这大大加快了构建、测试和代码检查的速度。如果您遇到过时或意外的行为，请使用以下命令重置缓存：

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

有关更多详细信息，请参阅 Nx 缓存文档。

并行性

新工作区在 nx.json 中设置 parallel，它控制 Nx 并发运行多少个任务：

nx.json

{
  "parallel": 8
}

如果您在核心数较少或内存有限的机器上构建，请降低此值。您还可以在每次调用时覆盖它：

pnpm

pnpm nx run-many --target build --parallel=4

yarn

yarn nx run-many --target build --parallel=4

npm

npx nx run-many --target build --parallel=4

bun

bunx nx run-many --target build --parallel=4

单一版本策略

默认的 monorepo 设置对基于 Node 和 Python 的项目都使用单一版本策略。

这意味着默认情况下，monorepo 中的所有项目使用相同版本的依赖项，减少了同一 monorepo 中的包遇到版本不匹配问题的情况。

从 Node 的角度来看，这意味着根目录有一个单一的锁文件，依赖项安装一次并链接到每个项目中。每个 Node 项目在其自己的 package.json 中声明其源代码导入的运行时依赖项，而共享的构建/测试工具位于根 package.json 的 devDependencies 中。通过将依赖项安装到该项目中来添加项目的运行时依赖项：

pnpm

pnpm add some-npm-package --filter my-project

yarn

yarn workspace @my-scope/my-project add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-project

bun

bun add some-npm-package --cwd packages/my-project

对于支持目录的包管理器（pnpm、yarn 和 bun），依赖项版本记录在目录中，并使用 catalog: 协议引用，为每个项目的 package.json 中的版本保持单一事实来源。对于 npm workspaces，我们推荐使用 syncpack 来对齐多个 package.json 文件中声明的版本。

从 Python 的角度来看，这意味着 monorepo 根目录中有一个单一的 .venv，所有依赖项都安装到其中。每个 Python 项目都有自己的 pyproject.toml，但这些依赖项的版本由 UV workspace 管理，随后写入根目录中的 uv.lock 文件。

常用命令

构建

构建工作区中的所有项目：

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

代码检查

对所有项目进行代码检查并自动修复：

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

测试

在所有项目中运行测试：

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

开发

在工作区中启动所有本地开发服务器：

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

有关更多详细信息，请参阅本地开发指南。

同步

运行任何同步生成器，例如同步 TypeScript 项目引用（有关更多详细信息，请参阅 ts#project 生成器指南）：

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

运行特定目标

您可以使用以下命令为特定项目运行特定目标：

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

例如：

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

这将运行所选目标以及它所依赖的目标。

包含的内容

代码检查

新工作区配置了 Biome 用于静态分析和代码格式化。运行 lint 检查所有项目的问题，lint --configuration=fix 自动修复它们。

MCP 配置

该插件的 MCP 服务器被配置为 Claude Code、Cursor、Kiro、Gemini CLI、GitHub Copilot 和 OpenAI Codex 的项目级 MCP 服务器，因此您的编码助手可以在无需任何设置的情况下发现并运行该插件的生成器。该配置与您的工作区一起提交，使您团队中的每个人都拥有相同的设置。删除您和您的团队不使用的编码助手的任何配置。

Git Secrets

工作区设置了 git-secrets 预提交钩子，在每次提交之前扫描暂存文件中的 AWS 凭证模式。这可以防止意外提交访问密钥、秘密密钥和其他敏感值。

该脚本被供应到工作区的 .git-secrets/git-secrets 中，并由 .husky/pre-commit 钩子运行，因此无需安装任何东西——但它不在您的 PATH 中，因此请通过路径调用它，而不是使用 git secrets。

抑制误报

git-secrets 中的模式使用 egrep 兼容的正则表达式。如果 git-secrets 阻止了不包含真实凭证的提交：

# Allow a specific regex pattern (-a is the allowed flag)
bash .git-secrets/git-secrets --add -a -- 'my-regex-pattern'

# Allow a literal string, escaping special characters (-l is the literal flag)
bash .git-secrets/git-secrets --add -a -l -- 'my-literal+string'

# List what is currently allowed
git config --get-all secrets.allowed

这些记录在您的本地 git 配置中，因此它们仅适用于您自己的克隆。要与您的团队共享抑制规则，请将其添加到仓库根目录的 .gitallowed 文件中——每行一个 egrep 兼容的正则表达式，与 <path>:<line-number>:<line-contents> 匹配：

.gitallowed

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

有关管理模式的完整详细信息，请参阅 git-secrets 文档。

Nx Plugin for AWS 配置

工作区在根目录附带一个 aws-nx-plugin.config.mts 文件。生成器读取此文件以选择合理的默认值，这样您就不必每次都传递相同的标志：

// aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: {
    provider: 'cdk', // or 'terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
  packageManager: {
    catalogs: true, // or false
  },
} satisfies AwsNxPluginConfig;

• iac.provider — 由生成基础设施的生成器（例如 ts#infra、ts#api、py#api）使用的默认基础设施即代码提供程序（cdk 或 terraform）。接受 --iac 标志的生成器默认为 inherit，它读取此值。
• containers.engine — 嵌入到生成的构建/推送/登录命令中的容器 CLI（docker 或 finch）。CDK 镜像资产构建也通过 CDK_DOCKER 环境变量获取此值。有关详细信息，请参阅 Docker 打包指南。
• packageManager.catalogs — 生成器是否在包管理器的目录中记录依赖项版本并使用 catalog: 协议引用它们（请参阅单一版本策略）。将其设置为 false 可让生成器将直接版本范围写入每个项目的 package.json 中。它对没有目录功能的 npm 没有影响。

license 生成器会向同一文件添加一个 license 键来配置其自身的行为。

您可以随时编辑任何设置——后续的生成器运行将获取新值。