class not found 主因是 autoload 映射未生成或失效，90% 问题源于 composer.json 配置错误、dump-autoload 执行时机不当、大小写/路径拼写错误；需检查 psr-4 末尾反斜杠、路径写法、bom、语法错误，并验证 vendor/autoload.php 引入及 $basedir 路径准确性。
Class not found 不是包没装，而是 autoload 映射没生成、没生效，或映射路径根本找不到文件——90% 的问题出在 composer.json 配置、dump-autoload 执行时机、大小写/路径拼写这三处。
看 composer dump-autoload -v 的实时输出，别猜
运行 composer dump-autoload -v，它会逐行打印扫描行为。如果输出里压根没出现你的命名空间（比如 App\），说明配置根本没被读取。常见原因：
-
composer.json有语法错误：漏逗号、多逗号、用中文引号、缩进错导致 JSON 解析失败 - PSR-4 键值末尾缺反斜杠：
"App"❌ 必须是"App\"✅ - 路径用了相对写法：
"./src/"或src❌ 正确是"src/"✅（末尾斜杠不能少） - 某 PHP 文件含 BOM、短标签未启用、或语法错误，
dump-autoload会在该文件卡住并报错，直接定位到具体行
查 vendor/composer/autoload_psr4.php 里的真实映射
这个文件是自动加载的最终执行依据，不是缓存，是真相。打开它，搜索你的命名空间前缀（如 'App\'），确认：
- 映射值是类似
$baseDir . '/src'的表达式，而不是硬编码路径 -
$baseDir实际指向的路径是否正确？部署时若代码目录和composer.json位置不一致，$baseDir可能算错（比如指向/var/www/html/vendor/../..，但实际代码在/app） - 类名拼写、大小写、斜杠方向是否与文件系统完全一致（
UserService.php≠userservice.php）
确认 vendor/autoload.php 被引入，且路径不依赖当前工作目录
入口脚本（如 index.php 或 CLI 脚本）顶部必须有且仅有一行有效引入：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
require __DIR__ . '/vendor/autoload.php';
注意：
- 用
__DIR__，不是./vendor/autoload.php或../vendor/autoload.php—— 相对路径在 CLI 或子目录下极易失效 - 引入语句不能被包裹在
if、函数或条件逻辑里，必须在任何类使用前无条件执行 - 运行
php -r "var_dump(file_exists(__DIR__ . '/vendor/autoload.php'));"确认路径存在 - 某些环境（如 PHP-FPM + opcache）可能缓存了旧的
autoload.php，需清 opcache 或重启服务
本地 path 仓库或新增包后类仍找不到
path 类型仓库不会自动触发 autoload 更新，本地包 require 后必须手动处理：
- 确认项目根
composer.json的repositories字段已声明该 path 源，且url是相对于该项目 composer.json 的路径（如"./packages/my-utils"） - 本地包自己的
composer.json必须含name和version（推荐"dev-main"），且已git init并有 commit - 安装时必须用分支名：
composer require mycompany/utils:dev-main，不能用*或^1.0 - 装完立刻运行
composer dump-autoload -o --dev（若包含autoload-dev） - 检查
vendor/mycompany/utils是否为符号链接（ls -l应显示-> ../packages/my-utils），否则 path 仓库根本没生效
最常被忽略的是：Linux 下大小写敏感 + PSR-4 字符串截取逻辑严格 + $baseDir 计算偏差，三者叠加会让类“凭空消失”。调试时别信 IDE 补全，用 php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\Services\UserService'));" 直接验证。
