Composer中文文档中关于PSR-4规范的高性能映射调优

Composer 的 PSR-4 高性能映射（dump-autoload -o）并不是默认行为，需要显式启用；不加 -o 时每次解析类名路径，I/O 开销较大；加 -o 后会生成静态的类名→路径查找表，这其实是生产环境的硬性要求，不是可有可无的选项。

强调一下：Composer 的 PSR-4 高性能映射（composer dump-autoload -o）并非“开箱即用”的默认行为，只有显式启用才会生效。不加 -o 时，Composer 会每次靠字符串解析来动态推算路径；加上 -o 后才会生成一张扁平的类名→文件路径静态查找表——很多人把它当成“可选优化”，但实际生产环境里，它其实是不可或缺的底线要求。

为什么不能跳过 dump-autoload -o

没有 -o 的时候，Composer 每次加载类都要做字符串解析：比如把 App\Controllers\Home 拆成 App 和 Controllers\Home，再按照 "App": "src/" 规则拼出 src/Controllers/Home.php。这个过程涉及正则匹配、目录遍历和 file_exists() 调用，I/O 开销相当明显。

• -o 会生成 vendor/composer/autoload_classmap.php，里面是完整的类名到绝对路径的键值对数组，加载时直接查表，零解析、零 I/O
• 自动化部署流水线里如果不加 -o，往往测试全绿，一上生产就卡顿明显，尤其在类数量大或跑在慢存储（比如 NFS）环境下更致命
• composer install --optimize-autoloader 等价于 composer install -o，但只对依赖包生效；项目自身的 psr-4 映射仍需手动 dump-autoload -o

classmap 和 psr-4 -o 不要混用

classmap 是另一种预生成映射机制，但它和 psr-4 -o 的原理完全不同：前者扫描指定目录下所有 PHP 文件并登记全部类，后者只登记符合 PSR-4 规则的类。两者共存时，Composer 会优先从 classmap 查表，冲突很容易就来了。

• 如果某个类同时满足 PSR-4 路径规则又被 classmap 扫到，classmap 的条目会覆盖 PSR-4 映射——可一旦你改了命名空间或移动了文件，classmap 不会自动更新，旧路径就此残留
• classmap 要求的路径必须真实存在且可读，否则 dump-autoload 会静默跳过该条目，不报错也不提示，最终映射直接缺失
• 除非真有特殊需求（比如加载非标准命名的遗留类），否则没必要为 PSR-4 类额外配置 classmap；专注写对 psr-4 再加上 -o 就足够了

Windows 和 Docker 下 -o 的行为一致性

路径分隔符和大小写敏感的问题在 -o 模式下会被放大——因为映射表一旦生成就是固化状态，运行时不再做任何路径转换或容错处理。

• JSON 里必须用正斜杠 /；哪怕在 Windows 上写了 "src\" 或 "src" 都会导致解析失败，dump-autoload 会忽略该条目（可以用 composer show -s 验证，看不到它）
• PSR-4 映射本身大小写敏感，-o 后只会更严格：类名 App\Helpers\StringHelper 必须对应 src/Helpers/StringHelper.php；文件名写成 stringhelper.php 或目录名小写成 helpers，在 Linux 容器里直接就是 Class not found
• Docker 构建阶段执行 composer dump-autoload -o 时，务必确保 src/ 目录已经 COPY 进镜像；否则生成的 classmap 为空或不完整，运行时全找不到类

最容易被忽视的其实是验证环节。生成 -o 之后，别只因为“没报错”就觉得万事大吉；用 composer show -s 确认你的命名空间前缀是不是列了出来，再跑一次 php -r "var_dump(class_exists('App\Controllers\Home'));" 实测加载结果——毕竟 PSR-4 的双向绑定（namespace ↔ path）只要一断开，-o 只会让错误更快暴露出来，而不是自动修复它。