许可证

管理工作区中的许可证：为您自己的代码同步 LICENSE 文件和源代码头部（license.source），并检查每个依赖项是否符合许可证允许列表（license.dependencies）。

使用方式

运行生成器

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - license
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:license

yarn

yarn nx g @aws/nx-plugin:license

npm

npx nx g @aws/nx-plugin:license

bun

bunx nx g @aws/nx-plugin:license

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:license --dry-run

yarn

yarn nx g @aws/nx-plugin:license --dry-run

npm

npx nx g @aws/nx-plugin:license --dry-run

bun

bunx nx g @aws/nx-plugin:license --dry-run

选项

参数	类型	默认值	描述
license	Apache-2.0 | MIT | ASL	Apache-2.0	您选择的许可证的 SPDX 许可证标识符
copyrightHolder	string	Amazon.com, Inc. or its affiliates	版权持有人，默认包含在 LICENSE 文件和源文件头部中。
dependencyCheck	boolean	true	配置一个 license-check 目标，当依赖项声明的许可证不在配置的允许列表中时失败。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器将创建或更新以下文件：

• nx.json 配置了运行许可证同步生成器的 lint 目标，并依赖于 license-check 目标
• aws-nx-plugin.config.mts 许可证源代码同步（license.source）和依赖项检查（license.dependencies）的配置

许可证头部与文件

生成器注册了一个同步生成器，作为 lint 目标的一部分执行，确保您的源文件包含正确的许可证头部，项目包含 LICENSE 文件，且在 package.json 和 pyproject.toml 中设置了许可元数据。

工作流程

每当构建项目时（lint 目标运行），许可证同步生成器会确保项目中的许可信息与配置匹配。若检测到不一致，您将收到如下消息：

  NX   工作区不同步

[@aws/nx-plugin:license#sync]: 项目 LICENSE 文件不同步：
- LICENSE
- packages/<my-project>LICENSE

项目 package.json 文件不同步：
- package.json

项目 pyproject.toml 文件不同步：
- pyproject.toml
- packages/<my-python-project>/pyproject.toml

以下源文件中的许可证头部不同步：
- packages/<my-project>/src/index.ts
- packages/<my-python-project>/main.py

这将在 CI 中导致错误。

? 是否要同步已识别的变更以使工作区保持最新？
是，同步变更并运行任务
否，不同步变更直接运行任务

选择 是 以同步变更。

检查变更

请确保将许可证同步生成器所做的变更提交至版本控制，以避免持续集成构建任务因许可证不同步而失败。

同步行为

许可证同步生成器执行三项主要任务：

1. 同步源文件许可证头部

同步生成器运行时，将确保工作区中所有源代码文件（基于配置）包含适当的许可证头部。头部以文件的第一个块注释或连续行注释形式写入（文件中的 shebang/hashbang 除外）。

2. 同步 LICENSE 文件

同步生成器运行时，将确保根 LICENSE 文件与配置的许可证一致，并确保所有子项目也包含正确的 LICENSE 文件。

3. 同步项目文件中的许可信息

同步生成器运行时，将确保 package.json 和 pyproject.toml 文件中的 license 字段设置为配置的许可证。

头部与文件配置

配置定义在工作区根目录的 aws-nx-plugin.config.mts 文件中。

SPDX 与版权持有者

可通过 spdx 配置属性随时更新所选许可证：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      spdx: 'MIT',
    },
  },
} satisfies AwsNxPluginConfig;

同步生成器运行时，所有 LICENSE 文件、package.json 和 pyproject.toml 文件将更新以反映配置的许可证。

可额外配置版权持有者和年份（部分 LICENSE 文件包含）：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      spdx: 'MIT',
      copyrightHolder: 'Amazon.com, Inc. or its affiliates',
      copyrightYear: 2025,
    },
  },
} satisfies AwsNxPluginConfig;

许可证头部内容

许可证头部内容可通过两种方式配置：

1. 内联内容：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: [
            'Copyright: My Company, Incorporated.',
            'Licensed under the MIT License',
            'All rights reserved',
          ];
        }
        // ... 格式配置
      }
    }
  }
} satisfies AwsNxPluginConfig;

2. 从文件加载：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // 相对于工作区根目录
        }
        // ... 格式配置
      }
    }
  }
} satisfies AwsNxPluginConfig;

头部格式

可通过 glob 模式为不同文件类型指定许可证头部格式。格式配置支持行注释、块注释或两者结合：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // 行注释
          '**/*.ts': {
            lineStart: '// ',
          },
          // 块注释
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // 带行前缀的块注释
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // 带头部/尾部的行注释
          '**/*.py': {
            blockStart: '# ------------',
            lineStart: '# ',
            blockEnd: '# ------------',
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

格式配置支持：

• blockStart: 许可证内容前的文本（如开启块注释）
• lineStart: 每行许可证内容前的文本
• lineEnd: 每行许可证内容后的文本
• blockEnd: 许可证内容后的文本（如结束块注释）

自定义注释语法

对于原生不支持的文件类型，可指定自定义注释语法以帮助同步生成器识别现有许可证头部：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.xyz': {
            lineStart: '## ',
          },
        },
        commentSyntax: {
          xyz: {
            line: '##', // 定义行注释语法
          },
          abc: {
            block: {
              // 定义块注释语法
              start: '<!--',
              end: '-->',
            },
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

从头部同步中排除文件

默认在 git 仓库中，所有 .gitignore 文件会被遵循以确保仅同步版本控制管理的文件。非 git 仓库中，所有文件均被考虑，除非在配置中显式排除。

可通过 glob 模式排除文件：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.ts': {
            lineStart: '// ',
          },
        },
        exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
      },
    },
  },
} satisfies AwsNxPluginConfig;

从文件同步中排除项目

默认同步所有 LICENSE、package.json 和 pyproject.toml 文件。

可通过 glob 模式排除特定项目或文件：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      files: {
        exclude: [
          // 不同步 LICENSE、package.json 或 pyproject.toml
          'packages/excluded-project',
          // 不同步 LICENSE，但同步 package.json 和/或 pyproject.toml
          'apps/internal/LICENSE',
        ];
      }
    }
  }
} satisfies AwsNxPluginConfig;

禁用许可证同步

许可证源代码同步通过配置中存在 license.source 键来启用。要禁用它：

1. 从 aws-nx-plugin.config.mts 配置中移除 license.source 部分（如果仍需依赖项许可证检查，可保留 license.dependencies）
2. 如果还想完全移除同步生成器，请从 targetDefaults.lint.syncGenerators 中移除 @aws/nx-plugin:license#sync 生成器

重新启用时，只需再次运行 license 生成器。

依赖项许可证检查

license 生成器还配置了一个 license-check 目标，当项目的某个依赖项（或任何传递依赖项）声明的许可证不在允许列表中时，该目标会失败。

运行方式

生成器会在根 project.json 中写入 license-check 目标：

project.json

{
  "targets": {
    "license-check": {
      "executor": "@aws/nx-plugin:license-check",
      "cache": true,
      "inputs": [
        "{workspaceRoot}/pnpm-lock.yaml",
        "{workspaceRoot}/aws-nx-plugin.config.mts"
      ],
      "options": {}
    }
  }
}

inputs 是为您的工作区计算的：仅包含实际存在的锁文件以及 aws-nx-plugin.config.mts，当启用 Python 依赖项检查时（即配置了 Python 收集器），还会包含 {workspaceRoot}/**/uv.lock glob。

您可以直接运行检查：

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

结果会根据您的锁文件和 aws-nx-plugin.config.mts 进行缓存 — 当没有任何变化时，重新运行是即时的。

收集器决定扫描的内容。npmCollector 使用 license-checker-rseidelsohn，pythonCollector 使用 pip-licenses。如果未找到已安装的依赖项，检查将通过且无需检查任何内容。

作为 lint/build 的一部分运行

依赖项许可证检查会在您对工作区中的任何项目执行 lint 或 build 时自动运行。license 生成器会将每个项目的 lint 目标连接到根 license-check 目标，项目生成器（ts#* 和 py#*）在运行时也会执行相同操作 — 因此无论生成器的运行顺序如何，检查都会被连接。

这意味着您无需显式运行检查，尽管您仍然可以使用 license-check 目标来执行：

pnpm

pnpm nx license-check

yarn

yarn nx license-check

npm

npx nx license-check

bun

bunx nx license-check

连接方式是在每个项目的 lint 目标上设置跨项目 dependsOn，指向根 license-check 目标。要在 lint 或 build 期间跳过检查，请设置 LICENSE_DEPENDENCY_CHECK=skip 环境变量：

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun LICENSE_DEPENDENCY_CHECK=skip lint

配置

默认情况下，检查使用内置的常见宽松许可证集（MIT、Apache-2.0、BSD、ISC 等），导出为 DEFAULT_LICENSE_ALLOWLIST。您可以在配置中扩展或覆盖它：

aws-nx-plugin.config.mts

import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';

export default {
  license: {
    // ...
    dependencies: {
      allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
      exceptions: [
        { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
      ],
    },
  },
} satisfies AwsNxPluginConfig;

View the full list of licenses in DEFAULT_LICENSE_ALLOWLIST

自定义允许列表

要限制允许列表，请用您自己的数组替换 DEFAULT_LICENSE_ALLOWLIST。要扩展它，请展开默认值并添加条目。条目通过 SPDX ID、完整许可证名称或任何列出的别名进行匹配（不区分大小写）。

单个包的例外

对于检查失败的包，使用 exceptions — 要么是因为它们的许可证不在允许列表中，要么是因为它们没有可检测的许可证元数据。reason 字段是必需的，以便审查者可以看到为什么授予例外。

exceptions: [
  {
    package: 'union',
    version: '0.5.0',
    reason: 'Package ships verbatim MIT text without declaring license',
  },
];

引入具有问题元数据的依赖项的生成器（例如 MCP 服务器生成器）会在运行时自动将所需的例外添加到您的配置中。

收集器

收集器发现依赖项并提取许可证元数据。内置收集器是 npmCollector()（扫描 node_modules）和 pythonCollector()（扫描 Python 虚拟环境）。许可证生成器默认配置 npmCollector()，并在存在 Python 项目时添加 pythonCollector()。

要实现自定义收集器，请符合 LicenseCollector 接口：

import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';

const myCollector = (): LicenseCollector => ({
  name: 'my-ecosystem',
  traceCommand: 'my-tool why <package>',
  async collect({ workspaceRoot }) {
    return [
      { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
    ];
  },
});

onDependency 钩子

license.dependencies 接受一个可选的 onDependency 回调，该回调会为每个发现的依赖项调用一次，无论它是否通过检查。它接收 { package, spdx }，其中 package 是包名称，spdx 是解析的 SPDX 许可证表达式。例外的 spdx 优先于原始声明的许可证，如果未声明许可证，spdx 可能是空字符串。

这是打印项目中所有许可证的便捷方式。运行 license-check 目标以查看输出：

aws-nx-plugin.config.mts

import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';

export default {
  license: {
    dependencies: {
      allow: DEFAULT_LICENSE_ALLOWLIST,
      onDependency: ({ package: pkg, spdx }) => {
        console.log(`${pkg} - ${spdx}`);
      },
    },
  },
} satisfies AwsNxPluginConfig;

禁用依赖项检查

依赖项许可证检查通过配置中存在 license.dependencies 键来启用。

要对单次运行禁用检查，请设置 LICENSE_DEPENDENCY_CHECK=skip 环境变量：

pnpm

pnpm LICENSE_DEPENDENCY_CHECK=skip lint

yarn

yarn LICENSE_DEPENDENCY_CHECK=skip lint

npm

npm run LICENSE_DEPENDENCY_CHECK=skip lint

bun

bun LICENSE_DEPENDENCY_CHECK=skip lint

要永久禁用，请从 aws-nx-plugin.config.mts 配置中移除 license.dependencies 键。您也可以使用 --dependencyCheck=false 重新运行 license 生成器以在不包含它的情况下进行脚手架。