第4章 Composer 自动加载机制

4. Composer 自动加载机制：PSR-4、PSR-0、Classmap、Files 自动加载的原理与配置

自动加载，说白了就是让 PHP 在用到某个类的时候，自动去把文件拽进来。不用你手动写一堆 require_once。我刚开始写 PHP 那会儿，每个文件顶部都是一长串的 require，后来接触了 Composer，才觉得这玩意儿真香。

Composer 提供了四种自动加载方式：PSR-4、PSR-0、Classmap、Files。每种都有自己的适用场景。我个人习惯，90% 的项目只用 PSR-4，剩下 10% 用 Classmap 或 Files 做补充。咱们一个一个来看。

PSR-4 是目前最主流的自动加载规范。它的核心思想很简单：命名空间前缀直接映射到目录路径。比如 App\Models\User 这个类，命名空间前缀 App\ 对应 src/ 目录，那么 Composer 就会去 src/Models/User.php 找这个文件。

配置方式也很直观，在 composer.json 里这样写：

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "MyLibrary\\": "lib/"
        }
    }
}

这里要注意，命名空间末尾的 \\ 不能少。我见过不少新手漏掉这个反斜杠，结果死活加载不上。嗯，细节决定成败。

PSR-4 最大的优势是性能好。它不需要扫描目录，直接根据命名空间计算文件路径。我在项目中遇到过，一个大型电商系统有上千个类文件，用 PSR-4 加载几乎没感觉到性能开销。

小技巧： 每次修改 composer.json 的 autoload 配置后，记得执行 composer dump-autoload 重新生成自动加载文件。我经常忘记这步，然后 debug 半天才发现。

PSR-0 是 PSR-4 的前身。它比 PSR-4 多了一个要求：类名中的下划线会被转换为目录分隔符。比如 MyLibrary_Models_User 这个类，PSR-0 会去 MyLibrary/Models/User.php 找。

配置方式类似：

{
    "autoload": {
        "psr-0": {
            "MyLibrary_": "src/"
        }
    }
}

为什么说它是备胎？因为 PSR-4 更灵活，性能也更好。PSR-0 需要处理下划线转换，多了一步操作。我现在基本不用 PSR-0 了，除非要兼容一些老旧的第三方库。

避坑指南： 我曾经接手过一个遗留项目，里面混用了 PSR-0 和 PSR-4，结果同一个类被两种方式加载，导致奇怪的报错。建议一个项目里统一用一种规范，别混着来。

Classmap 的原理很简单：扫描指定目录下的所有 PHP 文件，建立一个类名到文件路径的映射表。这个映射表保存在 vendor/composer/autoload_classmap.php 里。

配置方式：

{
    "autoload": {
        "classmap": [
            "src/",
            "lib/",
            "legacy/"
        ]
    }
}

Classmap 的优势是兼容性极强。不管你的类有没有命名空间，不管你的文件命名规不规范，只要在目录里，它都能找到。我一般在两种场景下用 Classmap：

但 Classmap 有个明显的缺点：每次添加新文件都要重新生成映射表。开发阶段频繁增删文件时，这很烦人。我建议开发时用 PSR-4，上线前再用 Classmap 做优化。

  性能对比： Classmap 的查找速度比 PSR-4 快，因为它直接查数组。但生成映射表的过程比较慢，尤其是目录下有大量文件时。我测试过一个项目，扫描 5000 个文件大概需要 2-3 秒。

Files 自动加载，说白了就是每次请求都自动加载指定的文件。它不关心类，只关心文件本身。

配置方式：

{
    "autoload": {
        "files": [
            "src/helpers.php",
            "src/functions.php"
        ]
    }
}

Files 最常见的用途是加载全局函数。因为 PHP 的函数不能像类那样自动加载，所以需要手动引入。我习惯把一些常用的辅助函数放在 helpers.php 里，然后用 Files 自动加载。

要注意的是，Files 加载的文件每次请求都会执行。如果文件里有耗时的操作，会影响性能。我曾经在一个项目里看到有人把数据库连接写在 functions.php 里，然后用 Files 加载...嗯，那性能简直惨不忍睹。

我个人建议的搭配方案：

Composer 提供了几个命令来管理自动加载：

# 重新生成自动加载文件
composer dump-autoload

# 生成优化后的 Classmap（生产环境用）
composer dump-autoload -o

# 生成权威的 Classmap（更彻底）
composer dump-autoload -a

-o 参数会把 PSR-4 和 PSR-0 的规则也编译成 Classmap，这样加载速度更快。-a 参数更彻底，它会完全忽略 PSR-4 和 PSR-0，只使用 Classmap。我一般在 CI/CD 流程里用 -o，上线前跑一次，能提升不少性能。

经验之谈： 如果你用 -a 参数，记得每次新增类文件后都要重新 dump。否则 Composer 找不到新类，会直接报错。我吃过这个亏，上线后才发现新加的类没加载到。

好了，自动加载这块就聊到这儿。你想想看，理解了这四种方式，基本上 Composer 的自动加载你就拿捏住了。下一章咱们聊聊依赖版本约束，那个才是真正让人头疼的地方。