根本原因是composer默认优先查询packagist.org而非私有仓库，必须显式禁用默认源：在repositories数组开头添加{"packagist.org": false}，且私有仓库type须为"composer"、url末尾必须带斜杠。
根本原因不是私有包没发布，而是 Composer 默认仍查 packagist.org —— 你的私有仓库只是 fallback，根本轮不到它匹配。
为什么加了私有仓库 URL 还是报 “could not find a matching version”
Composer 的 repositories 是按顺序查的，但默认会把 packagist.org 当作隐式最高优先级源。哪怕你写了 "type": "composer" 指向 Artifactory 或 Satis，只要没显式禁用默认源，Composer 就永远先去 packagist.org 查一遍，查不到才 fallback——而你的私有包显然不在那儿。
- 必须在
repositories数组里加一条：{"packagist.org": false} - 这条配置必须放在所有自定义仓库之前（顺序敏感）
- 私有仓库的
url末尾必须带斜杠，比如"https://packages.internal.com/"，少一个就 404 或重定向失败 -
type必须是"composer"，不是"package"或"vcs"（除非你真用 Git 直接拉）
私有包 require 后仍然找不到，检查 name 和 version 是否对得上
私有包自身的 composer.json 里 name 字段（如 "acme/utils"）必须和你在项目中 require 的完全一致：大小写、vendor 名、分隔符一个都不能错。版本号也一样——如果你发的是 v1.2.0 标签，就别写 "^1.3"；如果只推了 dev-main 分支，就得在项目根 composer.json 里加 "minimum-stability": "dev"，否则默认过滤掉所有 dev- 前缀版本。
- 运行
composer show -a acme/utils（换成你的包名），看输出里有没有你想要的版本及对应稳定性标记 - 确认私有仓库服务返回的
packages.json确实包含该包：直接curl https://packages.internal.com/p2/acme/utils.json，检查响应是否为合法 JSON 且含versions字段 - 私有包的
version字段不能留空，也不能写成dev这种无效值；推荐用 Git tag 自动推导，避免手填
auth.json 配置错误导致 401，但 Composer 不提示
报 “could not find a matching version” 有时其实是认证失败的假象：Composer 拿不到私有仓库元数据，就当它不存在，于是连版本匹配这步都跳过了。它不会说 “认证失败”，只会安静地 fallback 到 packagist.org，然后报错。
-
auth.json必须放在~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），权限设为600 - HTTP Basic 认证的 key 必须和仓库 URL 完全一致，包括端口：比如仓库是
https://repo.internal:8080/，key 就得是"repo.internal:8080" - 不要手动编辑
auth.json，用composer config --global http-basic.repo.internal:8080 username password写入，避免格式错误 - CI 环境中必须用
COMPOSER_AUTH环境变量注入，不能放文件里
镜像同步延迟让新版本“看起来不存在”
国内镜像（如阿里云）对私有仓库的元数据同步有 10–30 分钟延迟，尤其新发版或 dev- 分支。你本地 composer.lock 里记录的是旧快照哈希，而镜像已更新，结果就是 composer install 拉下来的 zip 包哈希和 lock 文件不匹配，触发校验失败中断。
- 验证是否真不同步：访问
https://mirrors.aliyun.com/composer/p2/vendor/package.json，看返回 JSON 是否含你要的版本 - 临时切回官方源测试：
composer config -g repo.packagist composer https://packagist.org，再试composer require - 如果确认是镜像延迟，别清缓存，等同步完成或换源更有效
- 真正要删的缓存路径是
~/.composer/cache/repo/https---mirrors-aliyun-com-composer/，composer clear-cache不清理这个
最常被忽略的一点：私有仓库问题从来不是单点故障。它往往同时涉及源配置、认证、包自身元数据、镜像同步、锁文件哈希五层，缺一不可。随便改一个地方就跑 composer install，大概率掩盖真实断点。
