先运行composer show -a maatwebsite/excel查看真实可用版本及稳定性标识（如(stable)、(dev)），若仅显示dev-main而无stable版，则^3.1等约束不匹配；再检查repositories配置、minimum-stability设置及镜像源同步延迟。
composer require 报 “Could not find a matching version” 怎么快速定位
这不是网络或镜像问题，大概率是版本约束和实际发布的 tag 不匹配。比如你写 "maatwebsite/excel": "^3.1"，但该包最新 stable 版其实是 3.1.43，而 ^3.1 本应匹配——但如果它只发布了 dev-main 或 v4.0.0-beta，且你没放开稳定性限制，Composer 就会直接跳过。
先用这个命令看真实可用版本：composer show -a maatwebsite/excel。输出里每行末尾的 (stable)、(dev) 或 (RC) 才是关键判断依据。
- 如果只有
dev-main行，说明没发布稳定版，不能用^3.1这类约束 - 如果显示
v3.1.43 (stable)，但你写的是~3.1.0，那没问题；写成~3.2.0就必然失败 - 注意
dev-前缀必须显式写出：要装开发分支就得写"maatwebsite/excel": "dev-main"，不能只写"main"
私有包或 VCS 包 require 失败但 search 能搜到
composer search 只查 Packagist 全局索引，不走你配的 repositories；而 composer require 严格按 composer.json 里的 repositories 顺序 + packagist.org 开关来执行。所以搜得到≠能装。
检查三件事：
- 运行
composer config repositories，确认输出里有你配的私有源，并且最后一项是{"packagist.org": false}（必须是独立对象、必须在数组末尾） - 如果用了 VCS 类型（如 GitHub 私库），
type必须是"vcs"，不是"git"或"github"；URL 必须是可git clone的地址，结尾不能带#main这类 ref - 私有 Git 仓库根目录下必须有合法的
composer.json，否则 Composer 读不到元数据，直接 404
加了 --no-update 还报版本不存在？检查 minimum-stability
即使只是下载包不更新依赖，composer require vendor/name:version --no-update 仍会校验版本是否满足当前项目的稳定性策略。默认 "minimum-stability": "stable" 会过滤掉所有 beta、dev、RC 版本。
临时解决方法（别改全局配置）：
- 指定分支安装：
composer require yansongda/pay:dev-main --no-update - 放宽单次命令的稳定性：
composer require yansongda/pay:dev-main --stability=dev --no-update - 避免改
composer.json的minimum-stability——它会影响后续所有require和update，容易引发连锁冲突
镜像源同步延迟导致新版本“找不到”
阿里云、腾讯云等国内镜像不是实时同步 Packagist 的。一个包刚在官方源发布，可能 1–6 小时后才出现在镜像里。此时 composer require 会提示“not found”，但 composer show -a 也查不到。
验证方式：
- 临时切回官方源：
composer config --global repo.packagist composer https://packagist.org - 再跑一次
composer show -a vendor/name，如果出来了，说明就是镜像延迟 - 不想全局切源？可在项目级临时覆盖：
composer config repo.packagist composer https://packagist.org（只影响当前项目）
真正麻烦的是私有包——公共镜像根本不会同步它，这时候错配 repositories 顺序或漏掉 {"packagist.org": false}，就永远找不到。
