如何使用Composer安装dotenv环境配置包？

本文共计779个文字，预计阅读时间需要4分钟。

直接运行以下命令失败，90%的原因是版本不匹配或扩展缺失，而不是命令写错了。

bashcomposer require vlucas/phpdotenv

• 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 的行为差异。这三个点一错，就变成“没报错，但啥都不生效”。