Class not found 的根源是 autoload 映射未更新或失效,而非包未安装;需依次验证包是否真安装、composer.json 配置是否正确、路径格式(如 PSR-4 末尾反斜杠)、符号链接状态、OPcache 缓存及大小写敏感问题。

不是 require 没装上,而是 autoload 映射没更新或根本没生效。 composer require 命令本应自动触发 dump-autoload,但实际中常因配置错误、权限问题或环境缓存导致类仍报 Class not found。关键不在重装,而在验证和重建映射链路。
composer require 后类还是找不到?先确认它真装上了
别跳过这步——很多“失效”其实是包压根没进项目。运行:composer show vendor/package-name
如果报 Package not found,说明 composer require 根本没成功(比如网络中断、镜像源不可用、或被 COMPOSER_MEMORY_LIMIT 中断)。
若正常输出版本和 autoload 字段,则问题锁定在自动加载环节。
- 检查
composer.json的require区块是否已新增该包(手动编辑后忘记保存也会失败) - 确认
vendor/vendor-name/package-name/目录存在且非空 - 运行
ls -la vendor/autoload.php,看修改时间是否晚于composer require执行时刻
dump-autoload 不生效?重点查这三处硬性条件
composer dump-autoload 默认只处理主项目的 autoload 配置,且对格式极其敏感。常见失效点:
-
"psr-4"键值末尾缺反斜杠:"App"❌ 必须写成"App\"✅(少一个 \,整个前缀不匹配) - 路径写了点号:
"./src/"或"src/"带前导.❌,Composer 只接受纯相对路径,如"src/"✅ -
composer.json有隐藏语法错误:BOM 头、单引号、中文逗号、多出的逗号——用composer validate直接定位
验证方式:加 -v 参数运行:composer dump-autoload -v
如果第一行就跳过 autoload 段,说明 JSON 解析失败;如果看到你的命名空间但没扫描文件,再查路径拼写和大小写。
本地 path 包改了代码却没生效?symlink 没建起来
你以为改的是源码,其实 PHP 加载的是 vendor/ 里的静态副本。这是最隐蔽的“失效”场景。
- Linux/macOS 下执行:
ls -la vendor/vendor-name/package-name,看到->才是符号链接成功 - Windows 下需管理员权限终端运行
composer install,否则 symlink 静默 fallback 到 copy 模式 - 关键配置不在主项目,而在本地包自己的
composer.json中必须含:"options": {"symlink": true} - Docker 场景下,挂载方式必须透传符号链接权限:
--cap-add=SYS_ADMIN+ 绑定挂载,不能只用-v
线上部署后 Class not found?OPCache 和路径大小写是真凶
本地能跑,线上崩,90% 是这两点作祟。
- PHP 的
opcache缓存了旧的 autoload 映射,仅刷新页面无效;必须清opcache或重启php-fpm - Linux 服务器严格区分大小写:
src/Http/Controllers/≠src/http/controllers/;开发机 macOS 常忽略这点,上线直接挂 - 别手动复制
vendor/目录上线——用composer install --no-dev --optimize-autoloader在服务器重装,确保映射与环境一致 - 检查
vendor/autoload.php权限:ls -l vendor/autoload.php,至少得是-rw-r--r--
真正卡住人的,从来不是命令没敲对,而是 autoload_psr4.php 里映射的路径和你文件系统里真实的路径,差了一个斜杠、一个大小写、或一个没删干净的 BOM。动手前,先让 composer dump-autoload -v 把话说明白。











