License

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

用法

运行生成器

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

VSCode

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

选项

参数	类型	默认值	描述
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   The workspace is out of sync

[@aws/nx-plugin:license#sync]: Project LICENSE files are out of sync:
- LICENSE
- packages/<my-project>LICENSE

Project package.json files are out of sync:
- package.json

Project pyproject.toml files are out of sync:
- pyproject.toml
- packages/<my-python-project>/pyproject.toml

License headers are out of sync in the following source files:
- packages/<my-project>/src/index.ts
- packages/<my-python-project>/main.py

This will result in an error in CI.

? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

选择 Yes 来同步更改。

审查更改

确保检查许可证同步生成器所做的更改并提交到版本控制，以确保任何持续集成构建任务不会因许可证不同步而失败。

同步行为

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

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',
          ];
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

2. 从文件加载：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relative to workspace root
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

头部格式

您可以使用 glob 模式指定不同文件类型的许可证头部格式。格式配置支持行注释、块注释或两者的组合：

aws-nx-plugin.config.mts

export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // Line comments
          '**/*.ts': {
            lineStart: '// ',
          },
          // Block comments
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // Block comments with line prefixes
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // Line comments with header/footer
          '**/*.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: '##', // Define line comment syntax
          },
          abc: {
            block: {
              // Define block comment syntax
              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: [
          // do not sync LICENSE file, package.json or pyproject.toml
          'packages/excluded-project',
          // do not sync LICENSE file, but sync package.json and/or 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 目标，当项目的某个依赖项（或任何传递依赖项）声明的许可证不在您的允许列表中时，该目标会失败。

如何运行

生成器将 license-check 目标写入您的根 project.json：

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;

查看 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 生成器以在没有它的情况下进行脚手架。