本文旨在解决 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
./tests/Unit ./tests/Feature
.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
以及一个简单的特性测试来验证数据库连接：
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 文件。
解决方案与最佳实践
为了确保测试环境正确加载 .env.testing，我们需要采取以下策略：
1. 清除配置缓存
最直接的解决方案是在运行测试之前清除所有缓存。这可以通过以下命令完成：
php artisan config:clear php artisan cache:clear php artisan view:clear php artisan route:clear php artisan optimize:clear # 推荐，清除所有缓存
执行这些命令后，再运行 php artisan test，Laravel 就会重新加载 .env 文件（或根据 APP_ENV 加载 .env.testing）。
2. 避免在开发/测试环境缓存配置
Laravel 官方强烈建议只在 生产环境 中缓存配置。在开发和测试环境中，应避免运行 php artisan config:cache。如果你在开发过程中习惯性地运行了 optimize 或 config:cache 命令，请务必在测试前清除缓存。
注意事项：
- 在部署流程中，config:cache 是一个重要的优化步骤。但请确保在部署到生产环境之前，你的所有 env() 调用都只存在于配置文件中，并且这些配置文件已经包含了所有必要的生产环境配置。
- 在本地开发或 CI/CD 测试流水线中，通常不需要缓存配置。
3. 使用 --env 选项（辅助方案）
尽管配置缓存是主要原因，但你也可以在运行测试时显式指定环境文件，作为辅助或临时解决方案：
php artisan test --env=testing
这个命令会强制 Laravel 在启动时使用 .env.testing 文件。然而，如果配置已经被缓存，这个选项的优先级可能会低于缓存的配置。因此，清除缓存仍然是更可靠和推荐的做法。
4. env() 函数的正确使用
再次强调，根据 Laravel 文档，env() 函数应该只在配置文件内部调用。例如：
config/database.php
return [
'connections' => [
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'unix_socket' => env('DB_SOCKET', ''),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'prefix' => '',
'prefix_indexes' => true,
'strict' => true,
'engine' => null,
'options' => extension_loaded('pdo_mysql') ? array_filter([
PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_SSL_CA'),
]) : [],
],
],
// ...
];在应用的其他部分（如控制器、服务、模型等）中，应通过 config() 助手函数来访问配置值，例如 config('database.connections.mysql.database')，而不是直接使用 env()。这样可以确保应用在配置被缓存后依然能正确读取到配置值。
总结
当 php artisan test 未能正确加载 .env.testing 时，几乎总是由于 Laravel 的配置缓存机制导致的。解决此问题的关键在于：
- 在测试前清除所有缓存，特别是配置缓存 (php artisan config:clear 或 php artisan optimize:clear)。
- 避免在开发和测试环境中缓存配置。
- 确保 env() 函数只在配置文件内部使用，并在其他地方通过 config() 助手函数访问配置。
遵循这些最佳实践，可以有效避免测试环境配置混淆的问题，确保测试的独立性和可靠性。
