Laravel API 测试中 401 错误的常见原因与解决方案-php教程-PHP中文网

Laravel API 测试中 401 错误的常见原因与解决方案

Laravel 单元测试中出现 401 Unauthorized 错误，通常源于 API 认证机制未正确初始化——尤其是 auth:api 中间件依赖的 Sanctum 或 Passport 环境未适配测试上下文。

laravel 单元测试中出现 401 unauthorized 错误，通常源于 api 认证机制未正确初始化——尤其是 `auth:api` 中间件依赖的 sanctum 或 passport 环境未适配测试上下文。

在 Laravel API 测试中，actingAs($user) 默认仅对 web 认证守卫生效；而你的控制器明确使用了 auth:api 中间件（如 Sanctum 或 Passport），此时必须显式指定守卫或手动颁发 API Token，否则请求将因无法通过 auth:api 验证而直接返回 401。

✅ 正确做法（以 Laravel Sanctum 为例）：
确保已安装并启用 Sanctum，并在 phpunit.xml 中配置环境：

<env name="SANCTUM_STATEFUL_DOMAINS" value="localhost,127.0.0.1"></env><env name="SESSION_DRIVER" value="array"></env><env name="CACHE_DRIVER" value="array"></env><env name="QUEUE_CONNECTION" value="sync"></env>

并在 tests/TestCase.php 的 setUp() 中调用 Sanctum::actingAs()：

use Laravel\Sanctum\Sanctum;

protected function setUp(): void
{
    parent::setUp();
    // 强制使用 Sanctum 认证，而非默认 web 守卫
    Sanctum::actingAs(
        User::factory()->create(),
        ['*'] // 允许所有权限（按需调整）
    );
}

⚠️ 若坚持在单个测试中手动处理，请避免仅用 ->actingAs($user)，而应：

Laravel

避免常见的Laravel错误：N+1查询、批量赋值、缓存陷阱及队列序列化陷阱。

下载

public function testDenyNonAdminUserAccess()
{
    $user = User::factory()->create(); // 确保用户已持久化（内存数据库有效）
    $author = Author::factory()->create();

    // ✅ 显式使用 Sanctum 登录（关键！）
    $user->withPersonalToken();

    $response = $this
        ->actingAs($user, 'sanctum') // ← 指定 'sanctum' 守卫
        ->postJson('/api/books', [
            'isbn' => '9788328302341',
            'title' => 'Clean code',
            'description' => 'Lorem ipsum',
            'authors' => [$author->id],
        ]);

    $response->assertStatus(403);
}

? 验证数据库状态（排除工厂数据未写入问题）：
Laravel 测试默认使用 sqlite :memory:，工厂数据必须显式创建才能存在。可在测试开头添加断言确认：

$this->assertEquals(0, User::count()); // 初始应为 0
$user = User::factory()->create();
$this->assertEquals(1, User::count()); // 确保创建成功

? 注意事项：

不要混用 auth:api 与 web 守卫逻辑；测试中务必匹配中间件所用守卫名称；
若使用 Passport，请改用 Passport::actingAs($user) 并确保已调用 Passport::useToken()；
检查 config/auth.php 中 api 守卫是否指向正确的 driver（如 sanctum）；
禁用 CSRF 验证：API 测试无需 VerifyCsrfToken，建议在 app/Http/Kernel.php 中为 api 中间件组移除该中间件，或在测试时临时禁用。

总结：401 根本原因不是认证失败，而是认证根本未触发——因为 actingAs() 默认不激活 api 守卫。显式指定守卫名称（如 'sanctum'）或使用对应认证工具类（Sanctum::actingAs），才是解决 Laravel API 测试 401 问题的标准实践。