Composer如何自动加载自定义类？（PSR-4配置示例）

psr-4映射需严格匹配：命名空间末尾加双反斜杠（如”app”），路径为相对composer.json的绝对路径片段（如”src/”），修改后必须运行composer dump-autoload生效。

composer.json 里怎么写 PSR-4 映射才生效

PSR-4 自动加载不会“猜”你的目录结构，必须严格匹配命名空间前缀和物理路径。常见错误是把 src/ 写成 ./src 或漏掉末尾斜杠，导致 composer dump-autoload 后类依然找不到。

• 映射值必须是相对于 composer.json 所在目录的**绝对路径片段**（不加 ./，也不用 __DIR__）
• 命名空间前缀末尾要带反斜杠，比如 "App"，不是 "App"；否则子命名空间如 AppControllersHome 会被截断
• 路径末尾不加斜杠，但目录必须真实存在——"src" 对应磁盘上的 ./src/ 目录
• 修改后一定要运行 composer dump-autoload，仅 composer install 不会重生成 autoload 配置

{     "autoload": {         "psr-4": {             "App": "src/"         }     } }

类文件名和路径为什么总报 class not found

PSR-4 要求类名完全对应文件路径，大小写敏感，且不依赖文件扩展名。linux/macos 下 MyClass.php 和 myclass.php 是两个文件，但 new MyClass() 只会找前者。

• 命名空间 AppControllers + 类名 HomeController → 必须放在 src/Controllers/HomeController.php
• 子目录名、类名、命名空间段必须一一对应，不能用下划线代替驼峰，比如 Home_controller.php 不行
• 文件编码必须是 UTF-8 无 bom，BOM 会导致解析时类声明被干扰，报 ParseError: syntax error
• 如果用了 traits 或 interfaces，它们同样要遵守 PSR-4 路径规则，不能只给 class 开绿灯

vendor/autoload.php 引入后还是找不到自定义类

根本原因通常是自动加载器没加载到你的配置——要么 composer.json 不在项目根目录，要么你手动 require 的是旧版 vendor/autoload.php（比如从其他项目复制过来的）。

• 确认 require __DIR__ . '/vendor/autoload.php'; 中的路径指向的是当前项目的 vendor/，不是父级或缓存副本
• 检查 vendor/composer/autoload_psr4.php 是否已包含你的映射项；如果没有，说明 dump-autoload 没成功执行或 JSON 格式有误
• 如果你在非标准位置运行脚本（比如 tests/runner.php），__DIR__ 可能不是项目根，要用 dirname(__DIR__) 往上跳
• 避免在 autoload 里混用 psr-4 和 files，后者是全局加载，容易掩盖路径问题

开发中改了命名空间但 autoload 没更新

Composer 不监听文件变更，它只认 composer.json 和 dump-autoload 命令。改完命名空间后不重新生成 autoload，PHP 还是按旧映射去找文件。

• 每次调整命名空间或目录结构，都要运行 composer dump-autoload -o（-o 表示优化，生成静态映射，开发期可省略但上线必须加）
• 如果用了 autoload-dev，记得 dev 环境也要单独 dump：composer dump-autoload --dev
• CI/CD 中容易忽略这点：构建镜像时若只 composer install，而没跑 dump-autoload，就会复现本地“明明能跑”的问题

PSR-4 看似简单，真正卡住人的永远是路径拼写、斜杠方向、大小写、以及那个你以为跑过了其实没跑的 dump-autoload。