Composer licenses命令配合自定义白名单实现合规性自动审批

处理 Composer 依赖的许可证检查，看起来是个标准流程，但实际操作中暗藏不少坑。直接拿 composer licenses 输出的纯文本表格去解析，是最容易翻车的方式之一——列宽是动态的，包名里可能藏着空格，许可证名称也随时可能被换行切断。一个不小心，MIT 就变成了 MI 和 T，BSD-3-Clause 在窄终端里也会自动折行。这样的数据拿去比对白名单，不出错才怪。

真正的解法是什么？是改用 JSON 输出。Composer 2.2 以上版本，可以这样处理：

composer licenses --format=json > licenses.json

拿到结构化的 JSON 数据后，用 jq 或者任意 JSON 解析器来提取 name、license、homepage 这些稳定字段，彻底绕开字符串匹配的陷阱。

• 但这个命令有几个前提：首先得确认 Composer 版本不低于 2.2，旧版本不支持 --format=json。
• --format=json 不会自动校验许可证的有效性，它只是把原始数据原封不动地转成 JSON。
• 容易忽略的一点是：某些包的 license 字段可能是数组（比如 ["MIT", "Apache-2.0"]），遍历时要逐个判断，确保至少有一个许可证在白名单内。

白名单配置应区分“允许”与“需人工复核”两类许可证

许可证审批从来不是简单的非黑即白。比如 GPL-2.0-only，在闭源项目里肯定行不通，但内部工具类项目也许可以通融一下；Unlicense 的法律效力在部分司法辖区还是个灰色地带，最好打上“需复核”的标签。所以，白名单不应该是个扁平列表，而是要有语义分级的。推荐用 YAML 来定义白名单文件 license-whitelist.yml：

allowed:  - MIT  - BSD-2-Clause  - BSD-3-Clause  - Apache-2.0review_required:  - GPL-2.0-only  - GPL-3.0-only  - AGPL-3.0-only  - Unlicense

• 脚本读取该文件后，对每个依赖的 license 字段逐项比对：先查 allowed，命中则跳过；再查 review_required，命中则记录并退出非零码。
• 不要把 proprietary 或空字符串当作合法许可证——这些应直接拒绝，不进白名单也不进复核列表。
• 注意大小写：Composer 输出的许可证名通常是大写（如 MIT），但有些包写成 mit 或 Mit，建议统一转大写再比对。

CI 中集成时必须检查 dev-dependencies 是否混入生产许可证风险

composer licenses 默认会把 require-dev 的包也统计进来。开发依赖（比如 phpunit、mockery）的许可证通常比较宽松，但问题在于：如果这些代码通过 class_alias 或打包脚本意外打进了生产构建，照样会触发合规风险。

• CI 脚本里最好显式分离：先用 composer install --no-dev 再跑许可证检查，或者用 jq 过滤掉 dev: true 的条目。
• 更稳妥的做法是生成两份报告：一份全量报告用于审计，一份仅包含 require 的清单用于准入卡点。
• 另外要留心的是，某些包（如 symfony/console）在 require 和 require-dev 中的版本不同，许可证也可能发生变化，不能只看锁文件顶层的声明。

自动化审批失败时要给出可定位的上下文，而非仅报错

只返回一句 ERROR: found disallowed license GPL-3.0-only in package foo/bar，对开发者来说根本不够用。他们需要立即知道：这个包是被谁引入的？是不是间接依赖？能不能升级到带宽松许可证的版本？建议在检测脚本里补全依赖路径：

composer depends --tree foo/bar 2>/dev/null | head -n 5

• 配合 composer show foo/bar 查看 license 字段，避免被 composer.json 中错误的声明误导。
• 如果白名单支持别名映射（比如把 BSD-3-Clause 映射到 BSD-3），日志中应明确写出“匹配别名”，方便审计追溯。
• 最容易被忽略的是私有包：它们的 license 字段经常为空或写成 proprietary，这类情况必须人工确认，绝对不能靠白名单绕过去。