Composer 自动发现失败主因是 composer.json 缺 type 字段、autoload 配置错误或未发布至 Packagist/私有仓库；类加载失败多因 PSR-4 映射失效、路径不匹配或 OPcache 缓存旧 autoload 文件。

自动发现失败不是 Composer 没“看到”你的包，而是它压根没被配置为可发现对象——composer.json 里缺 type 字段、没加 autoload、或没发布到 Packagist/私有仓库，都会导致“找不到包”或“类加载失败”这类表象。

为什么 composer require vendor/name 报 Package not found

这不是网络问题，也不是镜像失效，而是 Composer 根本没在任何已知源里登记这个包名。Packagist 不会自动收录所有 Git 仓库，必须显式提交或配置源。

• 先用 composer show -p vendor/name 查是否在 Packagist 公库注册；返回空就说明不在
• 如果是私有包，repositories 必须提前声明："type": "vcs" + 正确的 url，且该 Git 仓库根目录的 composer.json 中 name 字段必须和 require 完全一致（包括大小写）
• 国内镜像（如阿里云）只同步 Packagist 公库，对 vcs 类型仓库完全不代理——换镜像没用
• 删 vendor/ 和 composer.lock 后再 composer update vendor/name，避免旧缓存干扰解析

Class not found 但文件明明存在，怎么定位 autoload 问题

90% 的情况是 PSR-4 映射没生效，而不是类写错了。别急着改代码，先让 Composer 自己说清楚它到底扫了什么。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 运行 composer dump-autoload -v：看输出里有没有你的命名空间（如 "App\": "src/"），没有就说明 composer.json 的 autoload 段有语法错误（逗号漏了、引号不闭合、缩进错位）
• 检查 vendor/composer/autoload_psr4.php：搜索你的命名空间前缀，确认右边路径是否指向真实目录；注意末尾必须是 /，写成 "App\": "src" 会导致映射静默失效
• 类文件必须严格匹配路径推导逻辑：比如 AppServiceUserService → src/Service/UserService.php，大小写、文件名、命名空间声明三者必须完全一致
• 如果用了 classmap，它会优先于 PSR-4 生效；两个规则都配了却只走 classmap？查 autoload_classmap.php 里是否有该类名硬编码

执行 composer install 后新类仍加载失败，是不是要重装依赖

不需要删 vendor 或跑 update。纯调整自动加载规则，dump-autoload 就够了——install 和 update 都不会重刷 autoload，除非 lock 文件变动触发重装。

• 改完 composer.json 的 autoload 后，只运行 composer dump-autoload -o（带优化）即可
• 如果 CLI 下正常但 Web 请求报错，大概率是 OPcache 缓存了旧的 autoload_*.php；清 OPcache（opcache_reset() 或重启 PHP-FPM），别只清应用缓存
• CI 环境加了 --no-dev？那 autoload-dev 里的 "Tests\": "tests/" 就不会生效，新测试类自然找不到
• 验证类是否真进映射：运行 composer show --path vendor/name，或直接在脚本里 var_dump(class_exists('AppServiceUserService'))

最常被忽略的是：PSR-4 路径推导依赖命名空间末尾的反斜杠，以及 dump-autoload -v 输出里那一行“Skipping file xxx.php: syntax error”——它不会报错，但会安静跳过整个文件，连带里面所有类。