白名单直接限制composer.json中require字段可写入的包名与版本范围,仅允许白名单内的包出现在仓库packages.json中,未列入的包不会被SAT求解器识别,导致“Package not found”等解析失败;它不校验版本合规性,也不保证conflict/replace字段完整性,需配合版本字符串拦截与元数据全量导出。

白名单如何影响 Composer 的 require 字段解析
配置白名单本身不会改变 Composer 的解析逻辑,但会直接限制 composer.json 中 require 字段可写入的包名与版本范围。一旦白名单启用(比如在 Satis 或租户生成脚本中),Composer 安装时看到的元数据就只来自被允许的包——其余包根本不会出现在仓库的 packages.json 里,SAT 求解器连“见都没见过”,自然无法参与依赖图构建。
常见错误现象:composer install 报 Package foo/bar not found,但你确认它在 GitHub 上存在、也推到了私有 Git 仓库——问题出在白名单没包含 foo/bar,Satis 没把它纳入索引,packages.json 里压根没有这条记录。
- 白名单必须覆盖所有直接依赖 + 所有间接依赖涉及的包名(否则子依赖元数据缺失)
- 白名单不校验版本号,但若放行了
laravel/framework却没放行illuminate/support,安装 laravel 时就会卡在“找不到子依赖” - 白名单是静态字符串匹配,
monolog/monolog和monolog/monolog-dev视为两个不同包,需分别列入
白名单启用后 conflict 和 replace 字段是否还生效
只要白名单允许的包其 composer.json 被完整导出(含 conflict、replace 字段),这些约束就仍参与 SAT 求解。但现实中,很多白名单方案只做包名过滤,不保证元数据字段完整性——比如 Satis 默认不读 ZIP 包内 composer.json,若你没在 satis.json 中显式补全 require 映射,那 conflict 字段大概率为空,等于失效。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
使用场景:你想禁止某租户使用 dev-master 版本,仅靠白名单无法实现;必须配合版本校验逻辑(如拒绝含 dev-、@dev 的版本字符串),并在生成 composer.json 前拦截。
- 白名单 ≠ 安全围栏,它只管“能不能进仓库”,不管“进来的包是否合规”
-
conflict生效的前提是:该字段真实存在于仓库返回的包元数据中,而非原始composer.json里 - 如果你用
composer require --no-update本地写入一个白名单外的包,composer update时会直接报错退出,不会静默忽略
为什么加了白名单反而出现 Class not found
根本原因不是白名单本身,而是它导致下游依赖元数据断链。例如你白名单只放行了 laravel/framework:10.40.0,但没放行它硬依赖的 symfony/http-foundation:^6.4,Satis 就只导出 laravel/framework 的元数据,且 require 字段为空或不完整——Composer 解析时认为“这个包不依赖任何东西”,于是跳过安装 symfony/http-foundation,运行时自然 Class "Symfony\Component\HttpFoundation\Request" not found。
性能影响:白名单越窄,仓库索引体积越小,composer install 初始化元数据下载越快;但若窄到漏掉关键子依赖,后续要手动补、反复重试,实际耗时反而更长。
- 白名单必须和
require字段导出逻辑联动,不能只过滤包名,还要确保每个包的require、conflict、autoload全部写入packages.json - 验证方法:直接访问私有仓库的
packages.json,搜索目标包名,确认其require数组非空且内容合理 - 最容易被忽略的一点:白名单通常不处理
provide字段,但某些包(如psr/log-implementation)靠provide声明兼容性,漏掉会导致依赖解析失败

















