答案是先确认包是否真实存在，再检查repositories配置是否生效、packagist.org是否已禁用、minimum-stability是否匹配，最后排查镜像同步延迟、缓存残留及包名不可见字符；composer search仅查全局索引，require则严格按配置源+稳定性+元数据匹配。
包不存在，不是网络问题，也不是镜像失效——大概率是 Composer 根本没去你认为它该查的地方找。先确认包是否真实存在、再检查源配置是否生效，最后才考虑降级或换版本。
composer search 能搜到，但 require 报 “Could not find package”
这是因为 composer search 只查 packagist.org 全局索引，而 composer require 会严格按 repositories 配置顺序 + minimum-stability + 实际元数据匹配执行。
- 运行
composer config repositories，看输出里是否还包含https://repo.packagist.org—— 如果有，说明官方源没关，私有源或镜像再靠前也白搭 - 要禁用 packagist.org，必须在
composer.json的repositories数组末尾加一个独立对象：{"packagist.org": false}，不能写成"packagist": false或嵌套在其他仓库配置里 - 包只有
dev-main分支，但项目设了"minimum-stability": "stable"，就会直接跳过，报 “not found”，不是 “找不到对应版本” - 从网页或聊天记录复制包名时，容易带入零宽字符或全角空格，建议手动重打一遍
vendor/name
包名拼对了，也确认 Packagist 页面能打开，还是 404
这时重点排查镜像同步状态和本地缓存残留。
- 运行
composer config -g repo.packagist，确认当前全局镜像地址不是已停用的旧地址（如https://packagist.phpcomposer.com） - 临时切回官方源验证：
composer config -g repo.packagist composer https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19，再执行composer clear-cache - 新包刚推送到 GitHub，并不等于 Packagist 立刻可装——作者需主动提交或配好 webhook，否则你刷新十次也没用
- 国内镜像（阿里云、腾讯云等）同步有延迟，尤其对
dev分支、刚发布的 tag 或含敏感词的包，可能被过滤或暂未同步
私有包或 VCS 仓库始终 404
VCS 类型仓库不会出现在 Packagist 索引中，require 时才触发拉取；报 404 往往是元数据读取失败，而非网络不通。
-
type必须写"vcs"，写成"git"、"github"或漏掉，整条repositories配置会被静默忽略 -
url必须是合法的git clone地址，且结尾只能是.git（如https://gitlab.example.com/myorg/utils.git✅，带#main或路径后缀 ❌） - 目标仓库根目录必须有
composer.json，其中name字段必须与require中写的 **完全一致**（包括大小写） - GitHub 私有仓库需 token 认证：
auth.json必须存在且权限正确，URL 中不能带@username，否则 Composer 会跳过认证流程
确认包存在，但想装旧版本却失败
不是所有旧版本都还在 Packagist 上——有些已被归档、下架，或作者手动删除了 tag。降级操作本身也有明确约束。
- 先查可用历史版本：
composer show -a vendor/name，确认你要的1.2.5是否在列表中，且未被标记为abandoned - 安装必须显式指定精确版本号：
composer require vendor/name:1.2.5（注意中间无空格），不要用^1.2或~1.2.0，否则仍可能装到更新的小版本 - 如果报
Your requirements could not be resolved，大概率是依赖冲突，不是网络问题；运行composer why-not vendor/name:1.2.5查具体卡在哪 - 若必须绕过平台限制（如 PHP 版本不匹配），可用
--ignore-platform-reqs，但仅限调试，生产环境务必同步调整config.platform.php
最常被忽略的一点：composer.json 里写了 repositories，不代表它就一定生效——错一个字段，Composer 就静默忽略整个区块，继续查默认源。验证方式很简单：删掉 vendor/ 和 composer.lock，只留 composer.json，再跑一次 composer install，看它到底连了哪个源。
