先确认PHP版本和扩展：PHP≥8.0用^6.0，7.4用^4.3；必须启用mbstring和fileinfo；加载须在入口文件首行调用Dotenv::createImmutable(__DIR__)，.env路径需匹配，用getenv()测试而非$_ENV。
composer require vlucas/phpdotenv 报错？先看 PHP 版本和扩展
直接运行 composer require vlucas/phpdotenv 失败，90% 是因为版本不匹配或扩展缺失，不是命令写错了。
- PHP ≥ 8.0：用
vlucas/phpdotenv:^6.0（Laravel 10+/Symfony 7+ 默认适配） - PHP 7.4：只能装
vlucas/phpdotenv:^4.3，^5.0会静默拒绝 - 必须启用
mbstring和fileinfo扩展——缺一个，$dotenv->load()就可能不报错但也不生效 - 检查命令：
php -v、php -m | grep -E '^(mbstring|fileinfo)$'
为什么 new Dotenv() 找不到类？加载顺序和自动加载路径错了
类找不到，通常不是没装成功，而是自动加载机制没触发或路径不对。
- 别在
vendor/autoload.php之前手动require_once其他文件，否则命名空间注册失败 - 入口文件（如
public/index.php）第一行就该是：$dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..'); -
__DIR__指当前文件所在目录，如果.env在项目根目录而入口在public/，就得写__DIR__.'/..'，不能只写__DIR__ - 别用已废弃的
new Dotenv()构造函数，v4+ 起统一走createImmutable()或createUnsafeImmutable()
加载了但 getenv('DB_HOST') 还是 false？.env 文件格式和权限卡住了
Dotenv 对文件格式极其敏感，一个空格、BOM、换行符都可能导致整行被跳过。
- 用
file .env查 BOM：显示 “with UTF-8 Unicode (with BOM) text” 就得重存为无 BOM 的 UTF-8 - 等号前后不能有空格：
DB_HOST=localhost✅，DB_HOST = localhost❌（后者被当注释） - 变量名只支持字母、数字、下划线：
REDIS.HOST不会被识别，得改REDIS_HOST或 load 后手动putenv() - Linux/macOS 下检查权限：
ls -l .env，Web 进程用户（如www-data）必须有读权限，推荐chmod 600 .env
用 getenv() 测试比查 $_ENV 更可靠
$_ENV 是否填充取决于 variables_order PHP 配置，默认可能不包含 E，所以它为空不代表环境变量没加载成功。
- 始终用
getenv('APP_ENV')测试，这是 Dotenv 实际写入的位置 - 别在框架初始化后才加载 Dotenv，比如 Laravel 中不要在
config/app.php里调用Dotenv::createImmutable() - 如果用了 Docker，确保
php.ini中extension=mbstring和extension=fileinfo已启用——镜像里常漏掉fileinfo
实际项目中最容易被忽略的是：加载时机早于所有其他逻辑、.env 路径与入口文件相对位置、以及 getenv() 和 $_ENV 的行为差异。这三个点一错，就变成“没报错，但啥都不生效”。
