PSR-4加载失败主因是命名空间与文件路径不匹配，Composer仅字符串拼接路径，大小写、斜杠、目录层级任一错误均导致跳过；path仓库需update而非dump-autoload；classmap与PSR-4混用易“两头不靠”；vendor/autoload.php须在入口第一行绝对路径引入。
PSR-4 命名空间与文件路径不匹配是最常见原因
Composer 的 PSR-4 加载器不做文件扫描，只做字符串拼接：看到 namespace App\Http\Controllers;，就去拼路径 $baseDir . '/app/Http/Controllers/'，再加类名 IndexController.php。中间任何一环错位——大小写、目录层级、反斜杠数量——都会直接跳过文件。
常见错误包括：
-
"App\": "src/"配置中漏掉末尾反斜杠，写成"App": "src"，导致拼出srcIndexController.php - 命名空间是
App\Http\Controllers，但文件放在src/http/controllers/IndexController.php（Linux/macOS 下大小写敏感） - 类名
IndexController对应文件却是indexcontroller.php或index_controller.php - 在
src/根目录下放了UserService.php，但命名空间是App\Services，缺少Services/子目录
path 仓库改了 autoload 却不生效？别用 dump-autoload
本地 path 仓库的 composer.json 修改后，composer dump-autoload 完全无效——它只刷新主项目的映射，不重新读取 path 包的配置。
必须执行：
-
composer update vendor/package-name（强制重新解析该包的 autoload） - 确认 path 包的
composer.json已提交（git status检查），否则update仍读旧版 - 检查
vendor/composer/autoload_psr4.php，搜索你的命名空间前缀，确认路径值是绝对路径且指向你本地的src/目录，不是 vendor 下的副本 - Windows 用户需确保
"options": {"symlink": true}已启用，否则符号链接可能失效
classmap 和 PSR-4 混用引发“两头不靠”
当你同时配置了 PSR-4 和 classmap，且目标文件落在同一目录下，就容易出现类既不被 PSR-4 匹配（因 namespace 不对），又没被 classmap 扫到（因未触发重扫）。
例如：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
"psr-4": {"MyLib\": "lib/"}"classmap": ["lib/Utils.php"]- 但
Utils.php里没有namespace MyLib;
结果：MyLib\Utils 找不到（PSR-4 失败），Utils 也找不到（classmap 要求显式声明类名，且需 composer dump-autoload -a 强制重扫）。
建议：
- 有命名空间的新代码 → 全走 PSR-4
- 无命名空间的老工具类 → 单独用
classmap，并每次修改后运行composer dump-autoload -a - 全局函数文件（如
helpers.php）→ 放files类型，不是classmap
vendor/autoload.php 引入失败或时机错误
ThinkPHP、Laravel 等框架不会自动引入 vendor/autoload.php，全靠你手动写那一行。漏掉、路径错、或写在类使用之后，都会导致 Class not found。
验证方式：
- 入口文件（如
public/index.php）第一行必须是：require __DIR__ . '/../vendor/autoload.php'; - 加一句
var_dump(file_exists(__DIR__ . '/../vendor/autoload.php'));确认路径真实存在 - 不要用相对路径如
'vendor/autoload.php'，不同工作目录下会失效 - 避免把它塞进条件语句、中间件或配置加载逻辑里——必须在任何类实例化前执行
最易被忽略的一点：开发时习惯加 -o 参数生成优化映射，但它会掩盖 PSR-4 路径错误——classmap 可能碰巧扫到了文件，让你误以为配置正确；一旦上线删缓存或换环境，立刻暴露。日常调试请先用无参数的 composer dump-autoload，确认路径拼接逻辑走通，再考虑加 -o。
