“Package not found”主因是源配置失效、镜像未同步或元数据缓存未刷新；composer search仅查Packagist全局索引，require则严格按repositories顺序、minimum-stability及实际元数据匹配执行。
Composer 报“package not found”或“404 Not Found”，90% 不是网络不通，而是它压根没发请求到你认为该去的地方——源配置失效、镜像未同步、或元数据缓存没刷新。
为什么 composer search 能搜到，composer require 却失败？
composer search 只查 packagist.org 全局索引，不校验 PHP 版本、扩展、稳定性、repositories 配置；而 composer require 是真安装，会严格按 repositories 顺序 + minimum-stability + 实际元数据匹配执行。
- 你搜到的包可能只是 Packagist 上一个同名空包，你的私有源或镜像根本没被访问
- 包只有
dev-main版本，但项目设了"minimum-stability": "stable"→ 直接跳过，报 “not found”，不是 “版本不匹配” -
composer config repositories输出里如果还包含https://repo.packagist.org，说明官方源没禁用，私有源再靠前也白搭
composer require 卡在 “Loading composer repositories” 怎么排查？
这不是 Composer 在等网络响应，而是它在尝试读取远程 packages.json —— 如果镜像源地址错误、DNS 解析失败、或 TLS 握手异常，就会卡住或报错。
- 用
curl -I https://mirrors.aliyun.com/composer/packages.json直接测镜像连通性（替换为你当前配置的镜像 URL） - 运行
composer require vendor/name -vvv，看日志里是Reading from cache还是Downloading https://...；后者才说明真在发请求 - 若日志里反复出现
file could not be downloaded，优先切阿里云镜像：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，再composer clear-cache - 别信
ping packagist.org—— 它走 ICMP，而 Composer 走 HTTPS；用curl -v https://packagist.org才能模拟真实链路
VCS 类型仓库（Git/GitLab）为什么始终 404？
VCS 仓库不参与全局元数据索引，只在你明确 require vendor/name 时才触发拉取。报 404 的真实原因，往往不是网络不通，而是第一步元数据读取失败。
-
type必须写"vcs"，写成"git"、"github"或漏掉，整条配置被忽略 - URL 必须是可
git clone的地址，且结尾**不能带.git后缀以外的路径**（如https://gitlab.example.com/myorg/utils.git✅，https://gitlab.example.com/myorg/utils.git#main❌） - 目标仓库根目录必须有合法
composer.json，且其中"name"字段必须与你在require中写的完全一致（包括大小写） - 若需认证，GitHub 用
composer config -g github-oauth.github.com YOUR-TOKEN，GitLab 用composer config -g gitlab-token.gitlab.example.com TOKEN
最常被忽略的一点：镜像源同步有 5–30 分钟延迟，新发布的包在阿里云/腾讯云镜像里可能还没出现。别急着改配置，先打开浏览器访问 https://mirrors.aliyun.com/composer/p/vendor/name.json 看是否返回 404 —— 如果是，问题就出在镜像，不是你本地环境。
