答案是先验证包是否真实存在：访问https://packagist.org/packages/vendor/name确认页面可打开，再用composer search vendor/name和检查包名大小写、不可见字符；若存在则排查镜像失效、同步延迟、缓存残留或repositories配置错误。
包不存在，90%不是网络问题，而是 Composer 根本没去你配的源里找——它可能还在连已停用的旧镜像、被项目级配置覆盖、或元数据缓存过期。
先确认包名和存在性，别急着换源
报 Could not find package 或 404，第一反应不该是清缓存或换镜像。先验证包是否真实存在：
- 打开
https://packagist.org/packages/vendor/name（把vendor/name换成你要装的包），看是否返回 404 页面 - 运行
composer search vendor/name—— 如果没结果，Packagist 上确实没这个包 - 检查大小写：
monolog/monolog对，Monolog/monolog错；spatie/laravel-backup对，spatie/backup错 - 复制包名时小心不可见字符：从网页或聊天记录粘贴容易带零宽空格，建议手动重打一遍
检查当前生效的镜像源，别信 config 输出就完事
composer config -g repo.packagist 输出只是配置项，不代表实际生效。常见失效场景：
- 输出为空、
null或仍是https://packagist.org→ 全局镜像根本没配成功 - 项目根目录有
composer.json且含"repositories"字段（哪怕值是[]）→ 全局配置被**完全屏蔽**，此时要查composer config repo.packagist（不加-g） - Composer ≥ 2.2 必须用复数形式
repos.packagist，写成repo.packagist会被静默忽略 - URL 末尾漏了
/，比如https://mirrors.aliyun.com/composer→ 某些版本会拼出错路径导致 404
真正生效的证据是加 -vvv 后日志里出现 mirrors.aliyun.com 或 mirrors.tuna.tsinghua.edu.cn，而不是 packagist.org。
私有包或新发布包装不上？重点看 repositories 配置和 packagist.org 开关
自定义源写错一个字段，Composer 就会静默忽略它，继续查默认源，结果当然还是 not found。
-
"repositories"数组里必须显式禁用官方源：{"packagist.org": false}，且它得是**独立对象**、放在数组**末尾**，不能嵌套进其他仓库配置里 - 写成
"packagist": false或"packagist.com": false→ 静默无效，仍走官方源 - 包只有
dev-main版本，但项目设了"minimum-stability": "stable"→ 直接跳过，报 not found，不是版本不匹配 - 私有 VCS 源 URL 不合法（如少
https://、域名不可达、Git 仓库权限不足）→ Composer 不报错，只当没这个源
换源后必须 clear-cache，但更关键的是 --refresh 强制重载元数据
镜像站同步了新包，但 Composer 还在读本地缓存的 packages.json，就会“看到页面有 v3.6.0，却说找不到”。
- 执行
composer clear-cache是必须的，但还不够 - 真正刷新元数据要用
composer update --refresh，它会强制重新拉取所有源的packages.json - 之后再
composer require vendor/name或composer update vendor/name才能识别新版本 - 如果用了已停用镜像（如
https://packagist.phpcomposer.com或 Laravel China 镜像），换源前先删掉旧配置，否则clear-cache也救不了
最常被忽略的一点：项目级 repositories 配置和全局镜像冲突时，Composer 不警告、不提示，只默默按规则执行——你得自己用 composer config --list 和 composer config --list --global 对比，才能看出哪个在起作用。
