跳转到内容
@aws/nx-plugin
Blog

许可证

自动管理工作区中的 LICENSE 文件和源代码头部。

此生成器注册了一个同步生成器，作为 lint 目标的一部分执行，确保您的源文件符合所需的许可证内容和格式，同时确保项目的 LICENSE 文件正确无误，且相关项目文件（package.json、pyproject.toml）包含许可信息。

使用方式

运行生成器

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

    选项

    参数 类型 默认值 描述
    license string Apache-2.0 SPDX License Identifier for your chosen license
    copyrightHolder string Amazon.com, Inc. or its affiliates The copyright holder, included in the LICENSE file and source file headers by default.

    生成器输出

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

    • nx.json 配置了运行许可证同步生成器的 lint 目标
    • aws-nx-plugin.config.mts 许可证同步生成器的配置

    aws-nx-plugin.config.mts 中添加了许可证头部内容和格式的默认配置，用于为部分文件类型写入适当的头部。您可能需要进一步自定义；请参阅下方的配置部分。

    工作流程

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

    Terminal window
      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: {
        spdx: 'MIT',
      },
    } satisfies AwsNxPluginConfig;

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

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

    aws-nx-plugin.config.mts
    export default {
      license: {
        spdx: 'MIT',
        copyrightHolder: 'Amazon.com, Inc. or its affiliates',
        copyrightYear: 2025,
      },
    } satisfies AwsNxPluginConfig;

    许可证头部

    内容

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

    1. 内联内容：
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            lines: [
              'Copyright: My Company, Incorporated.',
              'Licensed under the MIT License',
              'All rights reserved',
            ];
          }
          // ... 格式配置
        }
      }
    } satisfies AwsNxPluginConfig;
    1. 从文件加载：
    aws-nx-plugin.config.mts
    export default {
      license: {
        header: {
          content: {
            filePath: 'license-header.txt'; // 相对于工作区根目录
          }
          // ... 格式配置
        }
      }
    } satisfies AwsNxPluginConfig;

    格式

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

    aws-nx-plugin.config.mts
    export default {
      license: {
        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: {
        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: {
        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: {
        files: {
          exclude: [
            // 不同步 LICENSE、package.json 或 pyproject.toml
            'packages/excluded-project',
            // 不同步 LICENSE，但同步 package.json 和/或 pyproject.toml
            'apps/internal/LICENSE',
          ];
        }
      }
    } satisfies AwsNxPluginConfig;

    禁用许可证同步

    禁用许可证同步生成器：

    1. 从 aws-nx-plugin.config.mts 配置中移除 license 部分（或删除该文件）
    2. 从 targetDefaults.lint.syncGenerators 中移除 @aws/nx-plugin:license#sync 生成器

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