Composer 静默忽略错误的 repositories 配置，导致私有包 not found；常见原因包括 type 错误、URL 缺失末尾 /、不可访问、漏配 Packagist 官方源、name 不匹配、tag 不合规、认证缺失、minimum-stability 限制、镜像同步延迟及缓存问题。
composer.json里repositories配置了但still not found
自定义源写错一个字段，Composer 就会静默忽略它，继续查默认源，结果当然还是 not found。常见错误包括：
-
type值没写或写成"vcs"但 URL 是 HTTP 地址（不是 Git 协议），应统一为"composer"类型并确保服务端提供packages.json -
url缺少末尾/，比如写成https://satis.example.com，实际请求会拼成https://satis.example.compackages.json→ 404 - URL 不可访问：用
curl -I https://satis.example.com/packages.json看是否返回HTTP/2 200；Nginx 返回 403/404 或 TLS 握手失败时，Composer 不报错，只 fallback - 项目级
repositories覆盖了全局镜像，但又漏掉了 Packagist 官方源声明 —— 只要写了"repositories"字段，Composer 就完全无视repo.packagist配置，必须手动补上：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
私有包require时报Could not fetch或Failed to download
这不是网络问题，而是 Composer 没法从你声明的源里解析出版本元数据。关键检查点：
- 私有仓库根目录的
composer.json必须含"name"字段，且格式为vendor/name，和你在require时写的完全一致（大小写、连字符、斜杠） - Git 仓库必须打合规 tag：
v1.0.0或1.0.0，不能是release-1.0、v1.0_final或带空格 - 若用 Satis 构建静态镜像，确认生成的
packages.json已上传，且所有p/xxx/yyy.json文件路径与内容可被直接curl获取 - GitHub/GitLab 私有仓库需认证：运行
composer config -g github-oauth.github.com YOUR_TOKEN，否则type: vcs会卡在元数据拉取阶段
composer search能搜到，但require报Package not found
composer search 查的是 Packagist 全量索引，而 require 实际安装时受三重限制：当前 repositories 配置、minimum-stability 设置、以及已锁死的 composer.lock 版本范围。
- 检查项目
composer.json是否设了"minimum-stability": "stable"（默认值），而你要装的私有包只有dev-main或beta版本 —— 此时加--stability=dev才能命中 -
composer show vendor/name返回 “no such package”？说明该包根本没进依赖解析树，不是版本冲突，是源不可见或 name 不匹配 - 已存在
composer.lock时，require会尝试兼容现有约束；若失败，先试composer require vendor/name --no-update，再单独composer update vendor/name
镜像同步延迟导致新包找不到
阿里云、腾讯云等镜像不是实时全量同步，尤其对刚发布的私有包、dev 分支、或未启用 webhook 的 GitHub 仓库，极易出现元数据缺失。最直接验证方式：
- 用
curl -I https://mirrors.aliyun.com/composer/p/vendor/name.json查状态码 —— 必须是HTTP/2 200，404 表示镜像还没同步 - 删掉元数据缓存目录：
rm -rf ~/.composer/cache/repo/https---mirrors.aliyun.com-composer（Linux/macOS）或%APPDATA%\Composer\cache\repo\https---mirrors.aliyun.com-composer（Windows） - 临时切回官方源验证：
composer config -g repo.packagist composer https://packagist.org/，再跑composer require；若成功，说明就是镜像同步问题 - 注意 Laravel China 镜像（
packagist.laravel-china.org）已于 2023 年底停服，仍在用必 404
真正卡住的地方往往不是“怎么配”，而是 Composer 对 repositories 字段的静默行为 —— 它不报错、不提示、不 fallback 到其他源，只是默默跳过。每次改完配置，务必用 composer config --list | grep repositories 和 curl -I 两级验证，别信“应该生效了”。
