Composer如何配置项目的开源许可证文件_集成特定的 License 插件【合规管理】

Composer的license字段仅为元数据声明，不触发任何行为；真正合规检查需显式启用--strict-licenses或使用composer audit配合jq解析，且LICENSE文件须手动创建并严格符合SPDX规范。

这里有个关键认知需要先摆正：Composer 本身并不提供所谓的“License插件”，市面上那些声称能自动检查、拦截甚至生成 LICENSE 文件的第三方 Composer 扩展，大多已经废弃或无人维护。指望通过一个插件来解决合规问题，这条路基本走不通。

composer.json 里 license 字段只是元数据，不触发任何行为

很多人以为在 composer.json 里写上 "license": "MIT" 或者 "license": ["MIT", "Apache-2.0"] 就万事大吉了。其实不然，这个字段的作用非常有限：它仅仅影响 Packagist 页面的显示、composer show --licenses 命令的输出，以及部分外部扫描工具的识别。它绝对不会：

• 自动为你生成 LICENSE 文件
• 阻止你安装带有 GPL 等传染性协议的依赖包
• 校验你自己的代码是否符合你声明的协议
• 在运行 composer install 时进行任何许可证相关的判断

说白了，这个字段就是个“声明”，仅此而已，不具备任何法律上的强制力。真要管理许可证合规，必须依赖其他机制。

真正起作用的 license 检查必须显式启用 --strict-licenses

好消息是，Composer 2.5+ 版本内置了基础的许可证白名单校验功能。但坏消息是，它默认是关闭的，需要你主动开启。启用方式只有两种：

• 在运行命令时显式加上参数：composer install --strict-licenses 或 composer update --strict-licenses
• 在 composer.json 的 config 部分配置白名单："config": { "license": ["MIT", "Apache-2.0"] }（注意路径是 config.license，不是顶层的 license 字段）

这里有几个关键点需要特别注意：

• 如果你没有加上 --strict-licenses 参数，那么 config.license 里的配置是完全无效的。
• SPDX ID 是大小写敏感的：写 "mit" 可以，但某些版本下写 "MIT" 反而可能导致匹配失败。
• "proprietary"（专有）和 "unlicensed"（未授权）这两个标识永远不会匹配任何开源白名单。
• 匹配规则是宽松的：只要依赖包的 license 字段中，有一个值落在你设置的白名单里，就算通过。

想自动检测高危协议？用 composer audit + jq

composer audit 是 Composer 2.5+ 内置的另一个实用命令，但它默认只报告安全漏洞，不涉及许可证风险。要让它帮你揪出许可证“地雷”，需要手动解析它的 JSON 输出：

composer audit --no-dev --format=json | jq '.violations[] | select(.severity == "critical") | select(.type == "license")'

哪些协议需要警惕？像 "AGPL-3.0-only"、"GPL-3.0-only"、"CC-BY-SA-4.0" 这类具有“传染性”的协议，在闭源项目中可能引发合规风险。

在 CI/CD 流程中，更稳妥的做法是直接扫描所有依赖的许可证声明：

composer show --no-dev --format=json | jq -r '.[].license // ["UNLICENSED"] | .[]' | grep -qE '^(MIT|Apache-2.0|BSD-3-Clause)$' || (echo "non-compliant license found"; exit 1)

这里有个细节：grep -qE 匹配的是标准的 SPDX ID 字符串，而不是自然语言描述。如果你依赖包的许可证字段写的是 "The MIT License"，那么上述命令很可能会漏检。

LICENSE 文件必须手动生成，且格式极其敏感

Composer 本身不读取、不写入、也不校验你磁盘上的 LICENSE 文件。但是，这个文件却是所有开源合规扫描工具（如 FOSSA、Snyk、GitHub License Detection）认定法律依据的“金标准”。出问题最常见的原因包括：

• 文件名错误：写成了 LICENSE.txt 或 license.md。正确的文件名是 LICENSE（无后缀，首字母大写）。
• 文本格式污染：从网页复制协议文本时，不小心带入了中文引号、全角空格或异常的自动换行，导致扫描器将其标记为 Unknown license。
• 内容错漏：年份写错、版权人名字拼错、必要的空行缺失。以 MIT 协议为例，第一行必须是完整的标题 MIT License，第二行必须是空行，第三行才是 Copyright (c) 2026 Your Name.。
• 文件被忽略：LICENSE 文件被错误地列入了 .gitignore。它不是密钥文件，必须提交到代码仓库中。

推荐一个可靠的做法：直接使用命令行下载官方原始文本，再替换年份和作者名，确保格式绝对正确：

curl -sL https://raw.githubusercontent.com/spdx/license-list-data/master/text/MIT.txt > LICENSE

最后，也是最容易被忽略的一点：composer.json 中的 license 字段声明、项目根目录的 LICENSE 文件内容、以及你实际分发的代码所遵循的协议，这三者必须完全一致。声明了 "MIT" 却没有附上 MIT 协议的全文，或者实际使用了 AGPL 协议却没有同步更新声明，这在法律和企业合规审查中都属于硬伤，务必避免。