确保 Laravel 测试环境正确加载 .env.testing 配置

admin 百科 2025-12-14 13

确保 Laravel 测试环境正确加载 .env.testing 配置-第1张图片-佛山资讯网

本文旨在解决 Laravel 项目中 `php artisan test` 命令未能正确加载 `.env.testing` 文件的问题。核心原因在于 Laravel 的配置缓存机制，当配置被缓存后，系统将不再读取 `.env` 文件。文章将详细解释这一机制，并提供清除缓存、避免在开发环境缓存配置以及正确使用 `env()` 函数等解决方案和最佳实践，确保测试环境隔离性和配置的准确性。

理解 Laravel 测试环境配置

在 Laravel 应用开发中，我们通常会为不同的环境（如开发、生产、测试）配置不同的环境变量。对于测试环境，Laravel 提供了 .env.testing 文件，并且可以通过 phpunit.xml 配置来指定测试时使用的环境。然而，开发者有时会遇到一个常见问题：即使 .env.testing 文件存在且 phpunit.xml 已正确配置 APP_ENV 为 testing，运行 php artisan test 时，应用仍然加载了默认的 .env 文件中的配置，而非 .env.testing。

问题现象：测试未加载 .env.testing

假设我们有以下配置：

phpunit.xml

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
>
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">./tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory suffix="Test.php">./tests/Feature</directory>
        </testsuite>
    </testsuites>
    <php>
        <server name="APP_ENV" value="testing"/>
        <server name="BCRYPT_ROUNDS" value="4"/>
        <server name="CACHE_DRIVER" value="array"/>
        <server name="MAIL_MAILER" value="array"/>
        <server name="QUEUE_CONNECTION" value="sync"/>
        <server name="SESSION_DRIVER" value="array"/>
        <server name="TELESCOPE_ENABLED" value="false"/>
    </php>
</phpunit>

登录后复制

.env.testing

APP_NAME=metrina
APP_ENV=testing
APP_KEY=base64:***************************
APP_DEBUG=true
APP_URL=http://localhost:81
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3307
DB_DATABASE=testing # 期望的测试数据库
DB_USERNAME=root
DB_PASSWORD=
DB_ENGINE=InnoDB

登录后复制

.env

APP_NAME=metrina
APP_ENV=local
APP_KEY=base64:***************************
APP_DEBUG=true
APP_URL=http://localhost:81
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3307
DB_DATABASE=actual # 实际的开发数据库
DB_USERNAME=root
DB_PASSWORD=
DB_ENGINE=InnoDB

登录后复制

以及一个简单的特性测试来验证数据库连接：

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
use Illuminate\Support\Facades\DB;

class TradeTest extends TestCase
{
    use RefreshDatabase;

    public function test_database_connection_is_testing()
    {
        $databaseName = DB::connection()->getDatabaseName();
        // 期望这里输出 "testing"
        $this->assertEquals('testing', $databaseName, '数据库名称应为 "testing"');
    }
}

登录后复制

当运行 php artisan test 时，我们可能会看到测试失败，或者通过 dd($databaseName) 发现输出的是 "actual" 而非 "testing"。这表明应用在测试时仍然使用了 .env 文件中的数据库配置。

核心原因：Laravel 配置缓存机制

这个问题的根本原因在于 Laravel 的配置缓存机制。当你执行 php artisan config:cache 命令时，Laravel 会将所有的配置信息编译成一个文件（通常位于 ./bootstrap/cache/config.php），以提高应用的加载性能。

一旦配置被缓存，Laravel 将不再加载 .env 文件。根据 Laravel 官方文档的说明，env() 函数只应在配置文件内部使用。一旦配置被缓存，env() 函数将只能返回系统级别的环境变量，而不会从 .env 文件中读取任何值。这意味着，即使 phpunit.xml 中设置了 APP_ENV=testing，如果配置已被缓存，Laravel 也不会重新解析 .env.testing 文件。