Composer require 报错分三类：版本冲突（用 why-not 查依赖阻塞）、网络超时（换国内镜像源）、自动加载失效（检查 autoload 配置并 dump-autoload）。
composer require 报错：找不到包或版本冲突
最常见的情况是 composer require 直接失败，提示 Could not find package xxx 或 Conclusion: don't install xxx。这不是网络问题，而是 Composer 在解依赖时卡在了版本约束上。
核心原因是：你当前项目已有的依赖（尤其是 composer.json 里的 require 和 require-dev）和你要加的新包之间存在无法调和的版本约束冲突。
- 先运行
composer why-not vendor/package:version（把vendor/package:version换成你要装的包名和具体版本），它会告诉你哪个已有包在阻止安装 - 如果没指定版本，
composer require vendor/package默认尝试装最新稳定版，但可能和你的 PHP 版本或现有包不兼容；显式写个低一点的版本试试，比如composer require monolog/monolog:^2.0 - 检查
composer.json顶部的"php": "xxx"是否太老——很多新包要求 PHP 8.0+，而你项目锁在 7.4 就必然失败
执行 composer require 卡住或超时
不是报错，而是命令长时间无响应，最后抛出 Connection timed out 或卡在 Loading composer repositories。这基本是源的问题，不是你本地网络真断了。
国内默认走 packagist.org，但它的 CDN 节点对大陆不稳定，且 Composer 会逐个尝试镜像源（包括国外的），导致整体变慢甚至假死。
- 换国内镜像：运行
composer config -g repo.packagist composer https://packagist.phpcomposer.com（旧版）或更推荐的composer config -g repo.packagist composer https://packagist.org+ 配置阿里云镜像插件（需装composer-plugin-aliyun-mirror） - 临时跳过平台检查加快解析：
composer require vendor/package --ignore-platform-reqs（仅调试用，上线前务必去掉） - 如果用了私有 Git 仓库或 Satis 服务，确认
repositories配置里的 URL 可访问、凭证有效，否则 Composer 会在后台反复重试直到超时
require 后 vendor/autoload.php 不生效 / 类找不到
命令成功返回，vendor/ 里确实生成了文件，但代码里 new SomeClass() 还是报 Class not found。问题不在安装，而在自动加载没触发或配置错了。
Composer 的自动加载靠 vendor/autoload.php，但它只加载符合 PSR-4/PSR-0 规则的命名空间，且依赖包自己得声明好 autoload 字段。
- 确认你
require的包在它的composer.json里写了"autoload": { "psr-4": { "Vendor\\Package\\": "src/" } }—— 如果没写，或者路径不对，就不会进自动加载映射 - 运行
composer dump-autoload强制重生成vendor/composer/autoload_*.php文件（尤其当你改过包内结构或手动挪过文件时） - 检查你自己的项目是否在
composer.json中漏配了autoload，导致自己写的类也没被扫到；例如缺了"autoload": { "psr-4": { "App\\": "app/" } }
require 安装了 dev-main 或 -dev 分支，不是稳定版
你没加任何参数，但 composer require vendor/package 装出来的却是 dev-main，甚至提示 Warning: The lock file is not up to date。这是 Composer 在找不到满足条件的稳定版 tag 时的降级行为。
根本原因：该包没有打符合语义化版本规范的 tag（比如 v1.2.3），或者你当前 PHP 版本/其他约束让它无法匹配任意一个 ^x.y 的稳定 release。
- 查包的真实发布情况：
composer show vendor/package --all看它有哪些可用版本，有没有1.x或2.0.0这类稳定版 - 强制指定稳定版：
composer require vendor/package:1.5.0（前提是这个版本存在且兼容） - 如果只有
dev-main可选，说明作者还没发正式版——别在生产环境用，风险在于 API 随时可能变，且不会触发 SemVer 兼容性保证
真正麻烦的不是报错本身，而是错误信息里混着“版本冲突”“网络超时”“自动加载失效”三种完全不同的故障域。很多人反复重试或换源，却没意识到自己其实在解决三个不同层面的问题。
