装不上 vlucas/phpdotenv 主因是 PHP 版本、扩展和命令不匹配：v6.x 需 PHP ≥ 8.0，v5.x 需 ≥ 7.2，v4.3 是 PHP 7.4 最后兼容版；必须启用 mbstring 和 fileinfo 扩展；需在项目根目录执行 composer require 并显式指定版本；.env 路径、格式及加载时机必须严格正确。
装不上 vlucas/phpdotenv，90% 是 PHP 版本、扩展、命令写法三者没对齐——不是包有问题，是环境没配平。
PHP 版本和 vlucas/phpdotenv 版本必须匹配
新版 vlucas/phpdotenv（v6.x）要求 PHP ≥ 8.0；v5.x 要求 PHP ≥ 7.2；v4.3 是 PHP 7.4 的最后兼容版本。硬装不匹配的版本会直接报 Your requirements could not be resolved。
- 运行
php -v确认当前版本：PHP 7.4 就只能用composer require vlucas/phpdotenv:^4.3 - PHP 8.0+ 可用
composer require vlucas/phpdotenv（默认装 v6.x） - 别指望 Composer 自动降级——它不会帮你选兼容版，必须显式指定
必须启用 mbstring 和 fileinfo 扩展
vlucas/phpdotenv v4+ 强依赖 mbstring，v5+ 还额外需要 fileinfo。缺任何一个，load() 可能静默失败，或抛出 Dotenv\Exception\InvalidPathException，而不是明确提示“扩展未启用”。
- 检查命令：
php -m | grep -E '^(mbstring|fileinfo)$' - 没输出？去
php.ini解开这两行：extension=mbstring、extension=fileinfo - Docker / CLI / PHP-FPM 的
php.ini可能不同，改完记得重启对应服务
composer require 报错后别乱试 autoload 加载
常见错误：手动 require_once 'vendor/autoload.php' 后再调 Dotenv::createImmutable()，结果报 Class 'Dotenv\Dotenv' not found。
立即学习“PHP免费学习笔记（深入）”；
- 根本原因：不是类不存在，是自动加载器没被正确注册——比如你在子目录下执行了
composer require，导致vendor/autoload.php生成路径错位 - 正确做法：确保在项目根目录执行命令；入口文件里直接写
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);，不要提前require_once - v5+ 必须用
createImmutable()，new Dotenv()已废弃，且不再支持load()返回值判断
.env 文件读不到变量？先盯住路径和格式
Dotenv::createImmutable() 默认只找传入路径下的 .env，不会向上递归。路径错、权限错、格式错，都会导致 $_ENV 和 getenv() 返回空，且不报错。
- 入口在
public/index.php？那__DIR__指向public，得写Dotenv::createImmutable(__DIR__.'/..') - 用
file .env检查是否带 BOM；Windows 用户注意右键属性不能勾“隐藏” - 等号两侧不能有空格：
DB_HOST=localhost✅，DB_HOST = localhost❌（整行被当注释跳过） - 变量名含点号（如
REDIS.HOST）默认被忽略——vlucas/phpdotenv只认字母、数字、下划线
最易被忽略的是加载时机：必须在任何业务代码、框架初始化、数据库连接之前执行 load()。哪怕只是早半行，getenv('APP_ENV') 都可能还是 false。
