工作空间

当您使用 @aws/nx-plugin 创建新工作空间时，预设生成器会设置一个 Nx monorepo，其中包含在 AWS 上构建的合理默认配置。

创建工作空间

pnpm create @aws/nx-workspace my-project

yarn create @aws/nx-workspace my-project

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

bun create @aws/nx-workspace my-project

选项

参数	类型	默认值	描述
addTsPlugin	boolean	true	是否添加 TypeScript 插件。
iacProvider	string	CDK	首选的基础设施即代码（IaC）提供商。
gitSecrets	boolean	true	是否配置 git-secrets 以防止提交 AWS 凭证。
containerEngine	string	infer	用于构建/推送/登录的容器引擎。'infer' 会在已安装 docker 时选择 docker，否则选择 finch（当两者都未安装时回退到 docker）。

工作空间结构

文件夹packages/ 您的项目存放在这里
- …
package.json Root package.json for your monorepo
nx.json Nx configuration (common targets, sync generators, caching)
tsconfig.base.json Root TypeScript configuration
aws-nx-plugin.config.mts Nx Plugin for AWS configuration
文件夹.git-secrets/ Vendored git-secrets bash script for credential scanning
- …
文件夹.husky/ Git hooks
- …

Nx

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

项目

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

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

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

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

缓存

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

pnpm nx reset

yarn nx reset

npx nx reset

bunx nx reset

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

单一版本策略

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

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

从 Node 的角度来看，这意味着在根目录有一个单一的锁文件，其中包含一个包含所有依赖项的 node_modules。如果您需要添加新的依赖项，请在根目录的 package.json 中添加。

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

常用命令

构建

构建工作空间中的所有项目：

pnpm build

yarn build

npm run build

bun build

代码检查

检查并自动修复所有项目：

pnpm lint

yarn lint

npm run lint

bun lint

测试

在所有项目中运行测试：

pnpm test

yarn test

npm run test

bun test

开发

如果您有一个网站，在本地启动它和所有连接的组件：

pnpm dev

yarn dev

npm run dev

bun dev

同步

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

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

运行特定目标

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

pnpm nx <target> <project>

yarn nx <target> <project>

npx nx <target> <project>

bunx nx <target> <project>

例如：

pnpm nx build website

yarn nx build website

npx nx build website

bunx nx build website

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

包含的内容

代码检查

新工作空间配置了 ESLint 用于静态分析，Prettier 用于代码格式化。运行 lint 会将两者应用于所有项目。

Git Secrets

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

抑制误报

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

# 允许特定的正则表达式模式
git secrets --add --allowed 'my-regex-pattern'

# 允许字面字符串（特殊字符会被转义）
git secrets --add --allowed --literal 'my-literal+string'

您还可以在仓库根目录创建一个 .gitallowed 文件，每行一个 egrep 兼容的正则表达式（通过版本控制与您的团队共享）：

# 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'
  },
} satisfies AwsNxPluginConfig;

iac.provider — 生成基础设施的生成器（例如 ts#infra、ts#trpc-api、py#fast-api）使用的默认基础设施即代码提供商（CDK 或 Terraform）。接受 --iacProvider 标志的生成器默认为 Inherit，它会读取此值。
containers.engine — 嵌入到生成的构建/推送/登录命令中的容器 CLI（docker 或 finch）。CDK 镜像资产构建也会通过 CDK_DOCKER 环境变量获取此值。有关详细信息，请参阅 Docker 打包指南。

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