vlucas/phpdotenv 安装失败主因是 PHP 版本过低（v6 需 ≥8.0）或未启用 mbstring 扩展；加载须在入口文件首行调用 createImmutable()，注意 .env 文件无 BOM、无空格、路径正确，且应使用 getenv() 而非 $_ENV 测试。
composer require vlucas/phpdotenv 会失败？先确认 PHP 版本和扩展
不是所有环境都能直接装 vlucas/phpdotenv，最常见原因是 PHP 版本太低或没开 mbstring 扩展。这个包从 v5 开始要求 PHP ≥ 7.2，v6 要求 ≥ 8.0；如果你用的是 Laravel 9+ 或 Symfony 6+ 项目，大概率得上 v6。
- 运行
php -v看版本，低于 8.0 就别硬上dotenvv6 - 运行
php -m | grep mbstring，没输出说明mbstring没启用——Docker 用户常漏这步，本地 MAMP/XAMPP 也得手动勾选 - 如果项目锁死了旧版 Composer（比如 1.x），
composer require可能拒绝安装高版本依赖，先跑composer self-update
加载 .env 文件的时机不对，$_ENV 为空？别在 autoload 里干这事
Dotenv 必须在框架启动前、任何业务代码执行前加载，否则 $_ENV 和 getenv() 都拿不到值。Laravel 自带加载逻辑，但纯 PHP 项目或自建脚手架容易在这里翻车。
- 不要把
Dotenv::createUnsafeImmutable()放进 Composer 的autoload.files—— 加载顺序不可控，可能晚于其他类的静态初始化 - 推荐写在入口文件最顶上，比如
public/index.php开头第一行就调用：<?php $dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..'); $dotenv->load();
- 用
createImmutable()而非create()：前者禁止运行时修改环境变量，避免意外覆盖，更安全
为什么 getenv('APP_ENV') 返回 false？检查 .env 文件格式和路径
Dotenv 对文件格式很敏感，一个空格、BOM 头、Windows 换行符都可能导致整行失效。它默认只读当前目录下 .env，不会自动向上查找父目录。
- 用
file .env看是否带 BOM（显示 “with UTF-8 Unicode (with BOM) text” 就要重存为无 BOM） - 确保等号前后没空格：
DB_HOST=localhost✅，DB_HOST = localhost❌（后者会被当成注释） - 路径写错是高频问题：如果
.env在项目根目录，而入口文件在public/，那__DIR__是public，得写Dotenv::createImmutable(__DIR__.'/..') - 变量名含点号（如
REDIS.HOST）会被跳过——Dotenv默认只认字母、数字、下划线，要用load()后再手动putenv()
测试环境变量是否生效，别只看 $_ENV
$_ENV 默认是关闭的（variables_order 不含 E），即使 Dotenv 加载成功，$_ENV['APP_ENV'] 也可能为空。真正可靠的是 getenv() 或 $_SERVER。
- 用
var_dump(getenv('APP_ENV'))测试，不是$_ENV - 如果
getenv()返回false但$_SERVER['APP_ENV']有值，说明Dotenv已加载，只是$_ENV未同步——这是预期行为，不用修 - CLI 和 Web 环境变量隔离：Web 服务器（Nginx/Apache）通常不继承 shell 的
ENV，所以Dotenv必须在 PHP 层加载，不能靠系统级设置
环境变量不是“写完 .env 就自动生效”，加载时机、文件编码、PHP 配置、作用域隔离，每个环节都卡得死死的。最容易忽略的是 CLI 下测试时用了不同工作目录，或者 IDE 内置终端没重载 shell 配置导致 getenv() 行为不一致。
