为何PHPUnit用classmap自动加载无需引入autoload.php，而PSR-4需要？

架构老林

2026-5-7

为什么PHPUnit示例用classmap自动加载时无需手动引入vendor/autoload.php？

我按照PHPUnit的EmailTest示例操作，使用classmap自动加载时测试能正常运行，但切换为PSR-4自动加载后，必须手动添加require __DIR__ . '/../vendor/autoload.php';才能避免「Class 'App\Email' not found」错误。请问这是什么原因？

我的代码如下：

composer.json

{
  "autoload": {
    "psr-4": {
      "App\\": "src"
    }
  },
  "require-dev": {
    "phpunit/phpunit": "^9"
  }
}

tests/EmailTest.php

<?php
declare(strict_types=1);

use PHPUnit\Framework\TestCase;
use App\Email;

require __DIR__ . '/../vendor/autoload.php';

final class EmailTest extends TestCase
{
    public function testCanBeCreatedFromValidEmailAddress(): void
    {
        $this->assertInstanceOf(
            Email::class,
            Email::fromString('user@example.com')
        );
    }

    public function testCannotBeCreatedFromInvalidEmailAddress(): void
    {
        $this->expectException(InvalidArgumentException::class);

        Email::fromString('invalid');
    }

    public function testCanBeUsedAsString(): void
    {
        $this->assertEquals(
            'user@example.com',
            Email::fromString('user@example.com')
        );
    }
}

src/Email.php

<?php
declare(strict_types=1);

namespace App;

final class Email
{
    private $email;

    private function __construct(string $email)
    {
        $this->ensureIsValidEmail($email);

        $this->email = $email;
    }

    public static function fromString(string $email): self
    {
        return new self($email);
    }

    public function __toString(): string
    {
        return $this->email;
    }

    private function ensureIsValidEmail(string $email): void
    {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException(
                sprintf(
                    '"%s" is not a valid email address',
                    $email
                )
            );
        }
    }
}

问题解答

这背后的核心差异在于Classmap和PSR-4自动加载的工作机制，再加上你运行测试的方式可能存在细节差异，具体来说：

1. Classmap 是静态预生成的映射表

当你使用Classmap自动加载时，执行composer dump-autoload后，Composer会提前扫描你指定的目录（比如src/），把所有类的全限定名和对应文件路径的映射关系写入vendor/composer/autoload_classmap.php。

如果你是通过vendor/bin/phpunit运行测试（这是PHPUnit官方推荐的方式），这个脚本的开头已经内置了引入vendor/autoload.php的代码——也就是说，Classmap的自动加载逻辑已经被自动初始化了，所以你不需要手动添加require语句，测试就能正常找到App\Email类。

2. PSR-4 是动态按需解析的规则

PSR-4则完全不同：它不会提前扫描目录生成映射，而是在类被首次引用时，根据你定义的命名空间与目录的对应规则（比如App\对应src/）动态计算文件路径，再尝试加载文件。

如果没有手动引入vendor/autoload.php，PHP的默认自动加载机制根本不知道你定义的PSR-4规则，所以当代码中引用App\Email时，PHP找不到对应的文件，自然会抛出「Class not found」错误。

3. 为什么你感觉Classmap时不需要`require`？

大概率是因为你一直用vendor/bin/phpunit运行测试——这个脚本帮你自动完成了autoload.php的引入。而切换到PSR-4后，可能你尝试过直接用php tests/EmailTest.php执行测试文件，此时没有触发vendor/bin/phpunit的自动引入逻辑，所以必须手动添加require才能让PSR-4的自动加载规则生效。

最佳实践

不管用哪种自动加载方式，都建议通过vendor/bin/phpunit运行测试，而不是直接执行单个测试文件。这样不仅能避免手动引入autoload.php的麻烦，还能让PHPUnit更好地处理测试套件、配置文件等内容。

内容的提问来源于stack exchange，提问作者Haibin Liu