如何配置Composer以遵循PSR-4规范，实现自动加载类文件？

本文共计985个文字，预计阅读时间需要4分钟。

改完`composer.json`中的`autoload`配置，不运行`composer dump-autoload`，则永久加载不到类——PSR-4不是监听文件、自动生效的机制，它只读`vendor/composer/autoload_psr4.php`这个静态快照。

composer.json 中 psr-4 键值对怎么写才不报错

PSR-4 映射是「命名空间前缀 → 目录路径」的一一对应，写错一个字符就会导致 Class not found：

• "App" 必须以双反斜杠结尾（JSON 中表示一个反斜杠），写成 "App" 或 "App\"（三个反斜杠）都会被解析失败或降级为 PSR-0
• 路径值是相对于 composer.json 所在位置的相对路径，不能以 / 开头（如 "/src/" 是非法绝对路径）
• 路径末尾推荐加 /（如 "src/"），避免拼成 srcMyClass.php；但若写成 "src"，某些 Composer 版本会警告
• 空字符串 "" 作为命名空间前缀虽语法允许，但会覆盖 Exception、PDO 等全局类，禁止使用

目录结构和文件名必须与命名空间严格对齐

Composer 不扫描目录，也不猜测文件名。它只做一件事：把 AppHttpMiddlewareAuth 拆成 App + Http/Middleware/Auth，再拼到配置的路径后面，得到 src/Http/Middleware/Auth.php：

• 命名空间每一段必须对应一级子目录：AppHttpControllers → src/Http/Controllers/
• 类文件名必须与最末级类名完全一致（大小写敏感）：Auth.php 里只能有 class Auth，不能是 auth.php 或 Auth2.php
• Linux/macOS 下 src/Http/Client.php 和 src/http/client.php 是两个不同路径，后者永远加载不到
• 路径必须真实存在：配了 "App": "src/"，但 src/ 目录不存在，composer dump-autoload 不报错，运行时才爆错

为什么 require vendor/autoload.php 后还是 Class not found

引入 vendor/autoload.php 只是加载自动加载器，能否找到类，取决于 autoload_psr4.php 里有没有映射，以及磁盘上路径是否真能对上：

• 检查 var_dump(include 'vendor/composer/autoload_psr4.php');，确认你的命名空间键是否出现在数组里
• 确认类文件顶部写了正确的 namespace 声明，且结尾无多余空格或 tab（如 namespace AppHttpControllers;✅，namespace AppHttpControllers ;❌）
• 开发中新增命名空间（如加了 "Utils": "lib/utils/"），必须重新运行 composer dump-autoload，composer install 不保证重生成 autoload 表
• 别用 require_once 手动引入类文件——这绕过了命名空间机制，new UtilsHelper() 仍会找不到

测试代码不要混进主 autoload

测试类不该进入生产环境的自动加载表，否则可能被误引入、引发依赖污染或安全风险：

• 用 autoload-dev 单独配置，例如："autoload-dev": { "psr-4": { "AppTests": "tests/" } }
• 这样 composer install --no-dev 时，tests/ 下的类不会写入 autoload_psr4.php
• CI/CD 中建议固定用 composer install --no-dev --optimize-autoloader，避免本地未提交的 autoload 配置干扰部署

最容易被忽略的是：修改 composer.json 后，你得自己敲命令刷新映射；Composer 不会提醒你忘了这一步，也不会在你保存文件时悄悄帮你执行。