添加到现有项目

并非每个项目都从 pnpm create @aws/nx-workspace 开始。如果您已经有一个 Nx workspace — 或者一个可以添加 Nx 的 monorepo — 您可以逐步采用 @aws/nx-plugin，而无需重新创建项目。

前置条件

必选

Git
Node >= 22（推荐使用NVM等工具管理Node版本）
- 通过运行node --version验证版本
PNPM >= 11（也可使用Yarn >= 4、Bun >= 1或NPM >= 10）
- 通过运行pnpm --version、yarn --version、bun --version或npm --version验证版本
UV >= 0.5.29
1. 安装Python 3.14：运行uv python install 3.14.0
2. 通过uv python list --only-installed验证安装
将AWS凭证配置到目标AWS账户（应用部署环境）

将 Nx 添加到非 Nx 项目

如果您的项目还没有使用 Nx，请先使用 nx init 添加它。这是 Nx 本身负责的步骤；插件建立在一个正常工作的 Nx 工作区之上。它适用于普通包、npm/pnpm/yarn/bun 工作区、Turborepo 或 Lerna monorepo：

pnpm dlx nx@23.0.2 init

yarn dlx nx@23.0.2 init

npx nx@23.0.2 init

bunx nx@23.0.2 init

按照提示将 Nx 添加到您的工作区。有关更多详细信息，请参阅 Nx Documentation。

pnpm 仅为允许列表中的包运行安装脚本，而 nx 需要其安装脚本 — 没有它，nx init 执行的安装可能会失败，在 pnpm-workspace.yaml 中留下 set this to true or false 占位符。在运行 nx init 之前将其添加到允许列表：

allowBuilds:
  - nx

非 Node 项目（Python、Go、Java、Rust 等）

Nx 和插件作为 npm 包分发，因此没有 Node.js 工具的项目在 nx init 可以执行任何有用操作之前需要一个最小的根 package.json：

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

创建该文件，然后照常运行 nx init 并添加插件。您现有的语言工具不受影响 — 插件生成的 Nx 项目（包括 Python 项目）与您现有的代码并存，您可以逐步将现有构建连接到 Nx。

要将您现有的项目纳入 Nx，根据语言的不同，您有几个选择：

具有官方 Nx 插件的语言 — Java (Gradle 或 Maven) 和 .NET 有专门的插件，可以自动推断您项目的任务。添加相关插件，例如 nx add @nx/gradle、nx add @nx/maven 或 nx add @nx/dotnet。
具有社区插件的语言 — 例如 Go (@nx-go/nx-go) 或 Rust (@monodon/rust)。浏览 Nx Plugin Registry 查找其他插件。
任何其他语言 — 向每个项目添加一个 project.json 并定义其目标以运行您现有的构建命令，这样 nx build <project>（和 nx run-many）就可以驱动它们。请参阅 workspace guide 了解如何设置 project.json 和目标。

单包项目

插件是为 monorepo 设计的 — 它将每个项目生成到 packages/ 下的自己的目录中。如果您从单包项目开始（根目录下有一个 package.json，源代码直接在其下，没有工作区），请在采用插件之前将现有包移动到 packages/ 中，以便您的项目与插件生成的项目并存：

创建一个 packages/<your-package>/ 目录，并将您的源代码、package.json 和 tsconfig.json 移动到其中。
创建一个新的根 package.json，作为工作区清单而不是项目本身：
package.json
```
{
  "name": "<your-workspace>",
  "private": true,
  "type": "module"
}
```
声明工作区，以便您的包管理器发现 packages/ 下的项目。对于 pnpm，添加一个 pnpm-workspace.yaml：
pnpm-workspace.yaml
```
packages:
  - packages/*
```
对于 npm/yarn/bun，向根 package.json 添加 workspaces 字段：
package.json
```
{
  "workspaces": ["packages/*"]
}
```
运行 nx init（如果您还没有运行），然后添加插件。

添加插件

使用 nx add，它会安装与您的 Nx 安装兼容的插件版本，然后运行其 init 生成器来配置您的工作区：

pnpm nx add @aws/nx-plugin

yarn nx add @aws/nx-plugin

npx nx add @aws/nx-plugin

bunx nx add @aws/nx-plugin

完成后，您的工作区就准备好了 — 选择您需要的生成器并开始生成项目。

此生成器配置的内容

添加插件会对工作区进行确定性更改，以便运行插件的生成器。它保留您工作区的模块格式：根 package.json 中有 type: "module" 的工作区保持 ESM，其他任何情况保持 CommonJS，生成的代码也遵循相同规则。它不会覆盖现有文件，根据您现有的配置，您可能需要在此步骤之后进行一些手动更改。

它创建或更新以下文件：

aws-nx-plugin.config.mts 记录您选择的 IaC 提供商（CDK 或 Terraform）和容器引擎；生成器从这里读取 iac.provider
nx.json 在 compile 目标上注册同步生成器（@nx/js:typescript-sync 和 @aws/nx-plugin:ts#sync），以便 TypeScript 项目引用保持同步
tsconfig.json 引用您工作区项目的根 TypeScript 配置，Nx 的 TypeScript 同步会保持其最新
tsconfig.base.json 插件的 TypeScript 项目扩展的共享编译器选项（参见下面它携带的内容）
pnpm-workspace.yaml（仅 pnpm）允许列出插件依赖项需要的构建脚本（@swc/core、esbuild、nx、sharp）
package.json 常见任务的便利脚本，以及 nx、@nx/js、@nx/workspace、typescript 和 Biome 开发依赖项
biome.json 默认 Biome 格式化器和 linter 配置
.mcp.json 为支持的编码代理配置 MCP server，除非禁用（还有 .cursor/、.kiro/、.gemini/、.vscode/ 和 .codex/ 等效项）

MCP server 配置可以使用 --mcp=false 禁用。

点击此处查看创建的 tsconfig.base.json 携带的编译器选项。

选项

参数	类型	默认值	描述
iac	cdk \| terraform	cdk	首选的 IaC 提供商。
mcp	boolean	true	是否配置 Nx Plugin for AWS MCP 服务器供编码代理使用。
containers	infer \| docker \| finch	infer	用于构建/推送/登录的容器引擎。'infer' 会在已安装 docker 时选择 docker,否则选择 finch(当两者都未安装时回退到 docker)。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装(如果后续生成器需要计算 Nx 项目图,仍会运行安装);最后统一安装一次。

故障排除

`The workspace is out of sync`

TypeScript 项目引用需要同步。init 注册同步生成器；运行：

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

安装期间出现 `ERR_PNPM_IGNORED_BUILDS`

pnpm 跳过未列入允许列表的包的安装脚本。init 在 pnpm-workspace.yaml 中允许列出插件工具需要的脚本（@swc/core、esbuild、nx、sharp），但该阻止可能在 nx add @aws/nx-plugin 本身期间触发 — 在 init 运行之前。运行 pnpm approve-builds 并批准列出的包（或将它们添加到 allowBuilds: 下），然后重新运行安装。

`nx sync` 挂起，或 `plugin worker ... exited before the connection was established`

如果同一个 node_modules 树中存在两个不同的 nx 版本（运行 npm ls nx 确认），它们的插件工作器 IPC 会死锁。init 生成器将根 nx devDependency 固定到插件自己的 @nx/* 包解析的版本，但稍后在不同补丁版本安装另一个 @nx/* 包可能会重新引入不匹配。将根 package.json 中的每个 nx 和 @nx/* 条目对齐到单一版本并重新安装。

`ts.readConfigFile is not a function`

您的工作区安装了 TypeScript 7，而 Nx 尚不支持 — Nx 的插件依赖于 TypeScript 的进程内编译器 API，而 TypeScript 7 不再提供该 API。将根 package.json 中的 typescript 固定到插件使用的版本（init 生成器会安装兼容版本）并重新安装。

`Recursive task invocation detected`

您的根 package.json 被注册为 Nx 项目（它有一个 "nx" 键，nx init 为单包仓库添加）并且带有 nx run-many --target build 的 build 脚本。然后 Nx 在根上推断出一个调用自身的 build 目标。将您的源代码移动到 packages/<your-package>/ 中，以便根成为工作区清单而不是项目 — 参见单包项目。（Nx 自己的独立预设通过在根包上设置 "nx": { "includedScripts": [] } 来避免这种情况；您可以将其作为更快的替代方案。）

添加插件后您的现有项目中出现 TypeScript 错误（`TS6059`、`TS7016`、`TS5011`、`NG4006`）

插件自己生成的项目在其每个项目的 tsconfig.lib.json 中携带它们需要的 TypeScript 设置，因此无论您的 tsconfig.base.json 如何，它们都能构建。这些错误反而出现在您预先存在的项目中，该项目继承了 init 创建的 tsconfig.base.json（带有 composite/emitDeclarationOnly/nodenext）但与这些设置不兼容 — 例如，Angular 编译器拒绝 emitDeclarationOnly（NG4006），或者在没有 rootDir 的情况下设置 outDir 的项目现在需要一个（TS5011）。为这些项目添加每个项目的 tsconfig 覆盖，重新声明冲突的选项（例如 "rootDir": "src"），或将插件的项目和您的项目指向单独的基础配置。

init 从不重写现有的 tsconfig.base.json，正是为了不会默默破坏从它继承的项目 — 解决这些不匹配是只有您才能为您的代码库做出的决定。

: “src”`），或将插件的项目和您的项目指向单独的基础配置。