Composer无白名单机制，需禁用默认源（composer config -g repo.packagist false）后手动添加可信仓库；键名必须用packagist，不可用packagist.org；项目级repositories优先于全局，但repo.packagist开关仅全局生效。
composer config 设置镜像白名单的正确姿势
Composer 本身不支持“白名单”机制，config repo.packagist.org 或 config repositories 只能覆盖或禁用默认源，不能按包名精确放行多个源。所谓“白名单”，实际是通过禁用默认源 + 手动声明可信仓库组合实现。
- 先执行
composer config -g repo.packagist false彻底关掉 Packagist 全局源（注意：不是packagist.org，这是旧写法，已弃用） - 再为每个需要的包显式添加仓库，例如 Laravel 包走官方镜像：
composer config -g repositories.laravel type composer和composer config -g repositories.laravel url https://mirrors.aliyun.com/composer/ - 如果某包只在 packagist.org 上有（比如小众私有包），就得单独加回：
composer config -g repositories.packagist type composer+composer config -g repositories.packagist url https://packagist.org，但此时它就不再受镜像加速
为什么 composer config --global repos 会失效或被忽略
常见错误是把仓库配置写成数组结构、或混用 packagist 和 packagist.org 键名。Composer v2+ 对仓库键名校验变严，packagist 是唯一合法的内置源标识符；写成 packagist.org 会被当成自定义仓库，但无法接管默认行为。
- 错误示例：
composer config -g repositories.packagist.org url https://mirrors.tuna.tsinghua.edu.cn/composer/→ 这个仓库不会替代默认源 - 正确做法：必须用
repo.packagist关闭默认源，再用repositories.xxx显式声明替代项 - 配置生效后，运行
composer config -g -l | grep repositories检查输出中是否含repo.packagist和你定义的repositories.*条目
限制下载源时 require 的包找不到怎么办
关掉默认源后，composer require foo/bar 会失败，除非该包已在某个已声明的仓库中注册。Composer 不会自动探测包归属，也不会 fallback 到其他源。
- 查包在哪：访问
https://packagist.org/packages/foo/bar，看页面右上角 “Source” 或 “Homepage” 是否指向 GitHub/GitLab —— 如果是，说明它只存在于 packagist.org，需手动加回官方源 - 临时方案：单次命令绕过限制，
composer require foo/bar --repository=https://packagist.org - 长期方案：把该包所在组织的镜像源加进
repositories，比如 VuePress 生态常用https://npm.pkg.github.com类型仓库，需配type: package+url+packages白名单数组（注意：这属于高级用法，仅限私有包）
composer.json 里写死源和全局 config 冲突吗
会。项目级 composer.json 中的 repositories 字段优先级高于全局 config，但 repo.packagist 这种开关类配置只在全局有效，项目里设了也不起作用。
- 项目内禁用默认源无效：写
"repo.packagist": false在composer.json的config下会被忽略 - 项目内可覆盖仓库：比如全局配了阿里云镜像，项目里又写了腾讯云镜像同名仓库（key 相同），则以项目为准
- 最稳做法：全局关默认源 + 全局配几个主流镜像（如 laravel、symfony、phpunit），项目里只补充私有源，避免重复和冲突
真正麻烦的是跨团队协作时，有人忘了关默认源，有人本地没配镜像，结果 CI 构建一半卡在 packagist.org。建议把 repo.packagist false 和基础镜像写进团队统一的 composer global config 初始化脚本里，而不是靠文档提醒。
