私有源配置错误是composer.lock里dist.url指向不可达地址的直接原因，需先验证该URL是否真实可访问、认证是否完备，并确认私有源未被全局镜像静默覆盖。
私有源配置错误是composer.lock里记录的dist.url指向不可达地址的直接原因，不是网络慢，而是路径拼错、认证缺失或镜像覆盖失效——先验证dist.url是否真实可访问，再看私有源是否被全局镜像静默劫持。
确认composer.lock里记录的dist.url是否真能下载
Composer 安装时不会重新解析包地址，而是严格按composer.lock中dist.url字段拉取。如果这个 URL 是私有 GitLab 仓库的 API 地址（如https://gitlab.example.com/api/v4/projects/123/repository/archive.zip?sha=abc），但返回 401 或 404，安装必然失败。
- 打开
composer.lock，搜索目标包名，找到dist块下的url字段 - 用
curl -I -u "token:" <url></url>测试（私有 Git 通常需 token 认证）；若返回HTTP/2 200且Content-Length非零，说明地址本身有效 - 若返回
401 Unauthorized，检查是否漏配auth.json；若返回404，确认项目 ID、分支名或 SHA 是否在私有源中仍存在
私有源被全局镜像覆盖导致dist.url被忽略
只要全局配置了repo.packagist，Composer 就会尝试把所有包（包括私有源声明的包）都从镜像站拉取——但它根本不会去镜像站查私有包，结果就是Could not find package或404。
- 运行
composer config -g repo.packagist，如果输出不是null或空，说明全局镜像已启用，它会干扰私有源 - 私有源必须显式声明为
type: "package"或type: "vcs"，且repositories顺序要靠前；否则 Composer 会跳过它，直奔全局镜像 - 临时禁用全局镜像：运行
composer config -g repo.packagist ""（清空），再重试composer install
auth.json没放对位置或格式错误
私有 Git 源（GitLab/GitHub Enterprise）依赖auth.json提供 token 或密码。它不读项目根目录的auth.json，只认~/.composer/auth.json（全局）或COMPOSER_AUTH环境变量。
- 检查
~/.composer/auth.json是否存在，内容是否为合法 JSON，例如：{"http-basic": {"gitlab.example.com": {"username": "token", "password": "glpat-xxx"}} - 若用 GitHub Token，域名必须写
github.com，不能写api.github.com；GitLab 同理，必须和dist.url里的 host 完全一致 - 权限必须是
600：chmod 600 ~/.composer/auth.json，否则 Composer 会静默忽略
删vendor/和composer.lock后重装仍失败？检查私有源是否被缓存污染
composer.lock里记录的是上一次成功解析出的dist.url，但如果私有源地址变更过（比如 GitLab 迁移、API 路径调整），旧 lock 文件就变成“过期契约”。清缓存也不管用，因为锁文件本身没更新。
- 先运行
composer clear-cache，确保不复用旧 zip 包 - 删掉
vendor/和composer.lock，但不要立刻composer install - 改用
composer update --with-dependencies，强制重新走一遍依赖解析，让 Composer 重新从私有源读composer.json并生成新dist.url - 若私有源本身不可达（如内网 GitLab 外网无法访问），这步会直接报错，比
install更早暴露问题点
最易被忽略的是：私有源 URL 和 auth.json 中的 host 必须字面完全一致，差一个www.或端口号都会认证失败；而composer.lock一旦生成，就不会自动刷新——它不是缓存，是契约，改源必须重算。
