vlucas/phpdotenv 5.5版本TypeError及APP_NAME无法输出问题求助

问题场景 #

升级vlucas/phpdotenv到5.5版本后，原2.4版本的代码触发类型错误，修改为工厂方法创建实例后不再报错，但无法读取.env中的APP_NAME值。

初始错误信息 #

Fatal error: Uncaught TypeError: Dotenv\Dotenv::__construct(): Argument #1 ($store) must be of type Dotenv\Store\StoreInterface, string given, called in C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\app\config_env.php on line 7 and defined in C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\vendor\vlucas\phpdotenv\src\Dotenv.php:60 Stack trace: #0 C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\app\config_env.php(7): Dotenv\Dotenv->__construct('C:\xampp\htdocs...') #1 C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\public\index.php(3): require_once('C:\xampp\htdocs...') #2 {main} thrown in C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\vendor\vlucas\phpdotenv\src\Dotenv.php on line 60

相关代码文件 #

index.php（路径：C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\public） #

<?php

require_once __DIR__ . '/../app/config/_env.php';

$app_name = getenv('APP_NAME');

echo $app_name;

.env（路径：C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I） #

APP_URL=http://localhost/PHPTheCompletePHPMVCourse_I
APP_ENV=local

APP_NAME="ACME E-commerce Store"

#database

DB_DRIVER='mysql'

DB_HOST=localhost

DB_NAME=store

DB_USERNAME=store

DB_PASSWORD=secret

_env.php（路径：C:\xampp\htdocs\PHPTheCompletePHPMVCourse_I\app\config） #

<?php

define('BASE_PATH', realpath(__DIR__.'/../../'));

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

$dotEnv = new Dotenv\Dotenv(BASE_PATH);

$dotEnv->load();

尝试修改后的_env.php代码 #

<?php

define('BASE_PATH', realpath(__DIR__.'/../../'));

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

$dotEnv = Dotenv\Dotenv::createImmutable(BASE_PATH);

$dotEnv->safeLoad();

问题分析 #

1. API版本变更：phpdotenv 5.x不再支持直接通过new Dotenv()实例化，必须使用createImmutable或createMutable工厂方法，这是初始类型错误的原因。
2. safeLoad()的隐藏问题：safeLoad()方法加载失败时不会抛出异常，无法排查.env文件是否成功加载。
3. .env文件的引号问题：5.x版本中，值两端的双引号会被解析为值的一部分（或导致解析异常），而2.x版本会自动去除引号，这是无法读取APP_NAME的核心原因。

解决方案 #

1. 修正.env文件格式 #

移除APP_NAME值的双引号，同时统一移除DB_DRIVER的单引号，确保格式符合5.x版本的解析规则：

APP_URL=http://localhost/PHPTheCompletePHPMVCourse_I
APP_ENV=local

APP_NAME=ACME E-commerce Store

#database

DB_DRIVER=mysql

DB_HOST=localhost

DB_NAME=store

DB_USERNAME=store

DB_PASSWORD=secret

2. 替换safeLoad()为load() #

load()方法在.env文件加载失败时会抛出异常，便于快速定位路径或文件存在性问题：

<?php

define('BASE_PATH', realpath(__DIR__.'/../../'));

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

// 可选：验证BASE_PATH是否指向.env所在目录
// echo BASE_PATH; exit;

$dotEnv = Dotenv\Dotenv::createImmutable(BASE_PATH);
$dotEnv->load(); // 替换safeLoad()为load()

3. 验证环境变量读取 #

修改后，index.php中的getenv('APP_NAME')即可正确输出值，也可以使用$_ENV['APP_NAME']或官方推荐的仓库读取方式：

$repository = Dotenv\Repository\RepositoryBuilder::createWithDefaultAdapters()->make();
$app_name = $repository->get('APP_NAME');

内容的提问来源于stack exchange，提问作者Nilantha Samararathna