失败大概率是PHP版本或扩展不匹配，不是命令写错：v6.x需PHP≥8.0且启用mbstring与fileinfo；PHP 7.4须显式装^4.3；加载必须在入口文件首行、路径正确、早于任何业务代码执行，并用getenv()而非$_ENV测试。
composer require vlucas/phpdotenv 为什么失败
大概率是 PHP 版本或扩展不匹配，不是命令写错了。composer require vlucas/phpdotenv 默认安装最新版（v6.x），要求 PHP ≥ 8.0 且必须启用 mbstring 和 fileinfo 扩展。PHP 7.4 项目要显式指定旧版本：composer require vlucas/phpdotenv:^4.3。
检查方法：
-
php -v确认版本 -
php -m | grep -E '^(mbstring|fileinfo)$'确认两个扩展已启用 - 若用 Docker，确保 php.ini 中
extension=mbstring和extension=fileinfo已取消注释
Dotenv 加载必须在入口文件最顶部
不是“写了就行”，而是必须早于任何依赖环境变量的代码执行。一旦某个类（比如数据库连接器）被自动加载器提前载入，它读取的 $_ENV 或 getenv() 就是空的原始值——错误会出现在下游（如 PDO 连接失败），但根因藏在加载时机里。
正确顺序（以 public/index.php 为例）：
require __DIR__.'/../vendor/autoload.php';-
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..');（注意路径：.env 在项目根目录，入口在 public/ 下，就得向上跳一级） -
$dotenv->load();（或safeLoad()，推荐后者） - 之后才能调用
getenv('DB_HOST')或访问$_SERVER['DB_HOST']
别在框架配置文件（如 config/database.php）里调用 Dotenv::createImmutable() —— 此时自动加载早已完成，为时已晚。
为什么 getenv() 返回空，但 $_ENV 也有值？
因为 vlucas/phpdotenv 默认只往 $_SERVER 写，不保证填充 $_ENV。PHP 的 variables_order 配置默认不含 E，所以 $_ENV 为空是正常现象，不代表变量没加载成功。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
安全读取方式：
- 始终用
getenv('APP_ENV')测试，这是 Dotenv 实际写入的位置 - 或统一从
$_SERVER['APP_ENV']取值（更可靠） - 不要依赖
$_ENV，除非你改过 php.ini 的variables_order = "EGPCS"
另外，.env 文件格式极敏感：等号前后不能有空格（DB_HOST = localhost ❌）、不能含 BOM（用 file .env 检查）、变量名只能含字母/数字/下划线（REDIS.HOST 不会被识别）。
多环境配置和自动化初始化
原生 phpdotenv 不自动切换 .env.development 或 .env.production，得手动组合。常见做法是先读 APP_ENV，再加载对应文件：
$env = getenv('APP_ENV') ?: 'production';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, ".env.{$env}");
$dotenv->safeLoad();
但更健壮的做法是利用 Composer 的 pre-autoload-dump 钩子，在生成 vendor/autoload.php 前就加载变量，确保所有类（包括框架引导逻辑）都能看到环境值：
- 创建
scripts/load-env.php，内容为：$dotenv = Dotenv\Dotenv::createImmutable(__DIR__); $dotenv->safeLoad(); - 在
composer.json中添加："pre-autoload-dump": "php scripts/load-env.php" - 运行
composer dump-autoload或composer install触发
这个时机点才是真正的“所有代码可见前”，比入口文件顶部还早一步——也是最容易被忽略的复杂点。
