私有源必须置于repositories数组首位，否则可能被跳过；正确写法为索引数组，含type和url，URL须以/结尾，{"packagist": true}作元数据兜底，全局config -g repo.packagist对私有源无效。
私有源必须放 repositories 数组首位
Composer 查找包的顺序就是 repositories 数组的书写顺序，一旦在中间或末尾写私有源，它可能根本不会被访问——因为公共镜像先返回了“包不存在”，Composer 就直接报 could not find package 了。私有包不走 packagist.org 元数据，也不受全局 repo.packagist 配置影响，必须显式声明。
正确写法是：
"repositories": [
{"type": "composer", "url": "https://pkgs.internal/artifactory/api/composer/internal/"},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"},
{"packagist": true}
]
注意三点：
-
url必须以/结尾，少一个斜杠会拼成https://pkgs.internal/packages.json（404） - 不能用对象写法：
"repositories": { "internal": { ... } }—— Composer 只读第一个键，其余静默丢弃 -
{"packagist": true}是兜底元数据查询，不是下载源，不参与 ZIP 下载，适合防新包漏索引
全局 config -g repo.packagist 对私有包完全无效
执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 只改 packagist.org 的代理地址，对任何 type: "composer" 的私有源都不起作用。更关键的是：只要项目 composer.json 里定义了 repositories 字段，全局配置就会被彻底屏蔽——哪怕你只写了 "repositories": []，也一样。
常见误判场景：
- CI 构建机用
runner用户运行命令，但-g写到了root的~/.composer/config.json，实际没生效 - 本地测试时用了全局镜像，一推到 GitLab CI 就报 401，因为容器里根本没有
auth.json或环境变量 - 以为配了阿里云镜像就能拉私有包，结果连认证环节都进不去
私有源认证失败的三个硬性检查点
报 401 Unauthorized 或 could not find package，90% 不是网络问题，而是认证断在某个环节。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
必须确认以下三项全部满足：
-
auth.json必须放在项目根目录（和composer.json同级），或通过COMPOSER_AUTH环境变量注入；~/.composer/auth.json在容器、GitHub Actions、宝塔等环境中通常不可见 - Token 权限必须包含
read:packages（GitLab）或read_package_registry（GitHub），仅api权限不够 - Artifactory/Nexus 的 Composer 仓库路径必须含
/api/composer/xxx/后缀，且后台需启用Enable Token Authentication
混用私有源和公共镜像时最容易丢包的写法
很多人把私有源 URL 写成 https://pkgs.internal/artifactory/api/composer/internal（缺末尾 /），或把多个源塞进一个对象里，结果 Composer 解析失败后静默跳过，最终只查了公共镜像就报错。
安全写法只有一条路：用索引数组，每个元素独立、带 type 和 url，顺序即查找优先级。例如：
"repositories": [
{"type": "composer", "url": "https://pkgs.internal/artifactory/api/composer/internal/"},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
]
不要加 "packagist": false ——这会彻底关掉官方源，一旦镜像同步延迟，新包就直接消失；要用 {"packagist": true} 做元数据兜底，它只查 packages.json，不下载 ZIP，不影响私有包逻辑。
最后提醒一句：私有源 URL 的协议、域名、路径、斜杠、认证方式，任何一个字符错了，Composer 都不会报明确错误，只会返回 404 或 401，然后默默放弃——你得自己对着日志里的真实请求 URL 逐字比对。
