必须显式声明{"packagist": false}置于repositories数组末尾,否则Composer仍会fallback至packagist.org;私有源需独立配置且顺序严格,白名单本质是精确控制repositories数组内容。

私有包必须显式关掉 packagist.org 回退
不加 "packagist": false,哪怕你写了内部 Satis 或 Private Packagist 地址,Composer 仍会悄悄去 packagist.org 查一遍——这不仅慢,还会暴露你项目里用了哪些私有包名。关键不是“有没有配私有源”,而是“有没有堵死官方源”。
常见错误现象:composer install 卡在 https://packagist.org/packages.json,或者日志里出现 Failed to download vendor/private-pkg: Could not fetch... 后又尝试访问 packagist.org。
-
"packagist": false必须是独立对象,不能塞进其他仓库配置里(比如不能写成{"type":"composer","url":"https://satis.internal/","packagist":false}) - 顺序严格:所有私有源(Satis、GitLab、path 等)放前面,
{"packagist": false}放数组末尾 - 如果团队还用了 VCS 类型仓库(如
"type": "git"),它们也得排在{"packagist": false}前面
白名单本质是 repositories 数组的精确控制
Composer 没有“白名单”这个配置项,所谓白名单,就是把 repositories 数组做成只包含你允许的源,且每个源都可验证、可审计。比如只允许一个 Satis 镜像 + 若干 path 本地包,其他一概不写。
使用场景:CI 流水线跑 composer install 时,不能依赖开发者本地环境或全局 config;所有源必须声明在项目级 composer.json 中。
- 避免用
composer config --global设置私有源——它对 CI 不生效,且不同项目可能冲突 - 不要在
repositories里留空或写占位符(如{"type":"composer","url":""}),Composer 会静默跳过并 fallback 到 packagist - 若需区分环境(如 dev/staging/prod),用
COMPOSER_REPOSITORIES环境变量注入 JSON 字符串,但必须确保该变量在 CI 和本地一致
path 仓库怎么加入白名单而不失控
团队共享本地开发包时,"type": "path" 是唯一可控方式,但它极易因路径问题失效,尤其在新成员 clone 项目后。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
关键点在于路径必须真实、相对、稳定:
-
url值必须是相对于项目根目录的相对路径,例如"../shared-packages/my-utils",不能含~、$HOME或绝对路径 - 目标目录下必须存在合法
composer.json,且其中name字段(如"acme/my-utils")要和主项目require中写的**逐字一致**(大小写、vendor 名、分隔符全算) - 本地包自己的
composer.json必须含"options": {"symlink": true},否则vendor/下只是副本,改代码不生效 - 首次引入必须用
composer update acme/my-utils,不是install——因为install只读 lock 文件,根本不解析repositories
验证白名单是否真正生效
别只看 composer install 成功了就认为 OK。真正生效的标准是:没有网络请求打向 packagist.org,且所有包都来自你指定的源。
执行以下命令观察行为:
-
composer install -vvv | grep -E "(packagist|https://)"—— 应只看到你配置的私有 URL,没有packagist.org -
composer show -p—— 检查每个已安装包的来源,确认私有包显示为path或你的 Satis 域名,而非packagist - 删掉
vendor/和composer.lock,再跑composer install—— 如果失败,说明某处路径错、name 错、或packagist: false没生效
最容易被忽略的是:团队成员各自机器上,../shared-packages/ 这个路径必须真实存在且结构一致。CI 里更要提前 git clone 共享包到固定位置,再用 --working-dir 或调整 url 路径指向它。稍有偏差,Composer 就静默跳过整个仓库,然后报 “Could not find package”。

















