Composer本身不支持白名单概念,所谓“白名单”实为组合配置:通过禁用packagist.org并仅配置可信私有仓库实现源限制,配合config.allow-plugins显式授权插件、require约束版本,辅以CI脚本或自定义插件校验包名。

Composer 本身不支持白名单规则
Composer 没有「白名单」这个概念,也没有 whitelist、allow-list 或类似配置项。你看到的“白名单”需求,通常是想限制项目中允许使用的包来源(比如只允许内部私有仓库)、或控制依赖解析行为(如禁止安装 dev 分支、禁用特定版本约束)。这些得靠组合使用其他机制实现,不是一条配置能搞定的。
用 repositories + packagist.org 禁用实现“仅允许指定源”
最接近白名单效果的做法:关闭 Packagist 公共索引,只保留你信任的私有仓库。这样 Composer 就无法从 packagist.org 解析任何包,所有依赖都必须能在你声明的 repositories 中找到。
在 composer.json 中写:
{
"repositories": [
{
"type": "composer",
"url": "https://your-private-repo.example.com"
}
],
"packagist.org": false
}
注意:"packagist.org": false 是全局开关,必须写在根级(和 repositories 同级),不是嵌套在某个字段里。漏掉这行,私有包可能仍会 fallback 到公共源,失去“白名单”效果。
- 如果私有仓库没镜像完整 packagist 数据,而项目又依赖未同步的包,
composer install会直接报错Could not find package xxx -
repositories顺序无关紧要,但packagist.org: false必须存在且为布尔false(不能是字符串"false") - 该设置不影响
composer global,只作用于当前项目
用 require 版本约束 + config.allow-plugins 控制行为边界
真正的“白名单”逻辑往往落在两处:依赖版本是否被允许引入,以及插件是否被允许执行。这两者都不能靠一个批量规则文件统一管理,但可以集中配置。
例如,禁止所有非语义化版本(避免 dev-master):
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
"require": {
"monolog/monolog": "^2.8",
"php": ">=8.1"
}
再配合 config.allow-plugins 显式放行可信插件:
"config": {
"allow-plugins": {
"phpstan/extension-installer": true,
"dealerdirect/phpcodesniffer-composer-installer": true
}
}
- 未列在
allow-plugins中的插件,在 Composer 2.2+ 默认被拒绝加载,报错类似The plugin xxx is not allowed -
require里写死具体版本范围,比留空或用*更可控;但无法阻止子依赖带入意外版本,需配合composer.lock固化 - 没有
whitelist-version-patterns这类通配配置项,正则匹配需靠 CI 脚本或自定义插件实现
需要真·批量白名单?得自己写插件或加 CI 检查
如果你的场景是“只允许引入公司 A/B/C 的包,其余一律拒用”,Composer 原生做不到批量声明。可行路径只有两个:
- 写一个 Composer Plugin,在
PreFileDownloadEvent或PackageEvents::POST_PACKAGE_INSTALL阶段检查$package->getName()是否匹配预设列表,不匹配就 throw 异常 - 在 CI 中跑脚本:解析
composer.lock,提取所有packages和packages-dev的name字段,用grep -v或 PHP 脚本比对白名单文件(如 JSON 列表),不匹配就 exit 1
这类方案绕不开代码或脚本,也意味着白名单维护成本转移到了外部——它不再是 Composer 的配置问题,而是工程流程问题。
最容易被忽略的是:很多人以为 repositories 配置能“过滤包名”,其实它只影响包的发现路径,不校验包名本身。哪怕你只配了一个私有源,只要那个源返回了 laravel/framework 的元数据,Composer 照样会装——所以真正兜底的永远是 lock 文件审查或运行时拦截。










