Composer 不自动加载 .env 文件，因其仅为依赖管理工具；需用 vlucas/phpdotenv 等库手动解析并注入环境变量，且须注意 variables_order、BOM、引号、加载时机及生产环境安全分发。
为什么 .env 文件在 Composer 项目里不自动生效
Composer 本身不读取或解析 .env 文件——它只是 PHP 的依赖管理工具，不是运行时环境配置系统。你执行 composer install 或 composer require 时，所有环境变量（比如数据库密码、API 密钥）都得靠 PHP 应用自己加载。常见错误是把 .env 放进项目根目录就以为“自动生效”，结果 getenv('DB_PASSWORD') 返回 false 或空字符串。
真正起作用的是第三方库（最常用的是 vizualis/vizualis-env 或更主流的 vlucas/phpdotenv），它们负责读取文件、解析键值、注入到 $_ENV 和 $_SERVER，并让 getenv() 可用。
如何用 vlucas/phpdotenv 正确加载 .env
这是目前最稳定、文档最清晰的方案，支持 PHP 7.2+，且默认启用变量嵌套和类型转换（如 DEBUG=true → bool(true)）。
- 运行
composer require vlucas/phpdotenv安装 - 在项目入口（如
index.php或public/index.php）顶部尽早加载，必须在任何依赖环境变量的代码之前 -
.env文件需放在项目根目录（与composer.json同级），不能放在vendor/或子目录下 - 加载示例（注意
Dotenv类名大小写）：
<?php require_once __DIR__.'/vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
// 此后 getenv('APP_ENV') 才有效
getenv() 返回空？检查这几点
即使用了 phpdotenv，getenv() 仍可能返回空，原因很具体：
- PHP 配置中
variables_order没包含E（即不读取环境变量）——检查phpinfo()输出，确保该项含EGPCS或至少E -
.env文件末尾有 BOM 头（尤其 Windows 编辑器保存时），会导致解析失败；用file -i .env或 VS Code 查看编码，保存为 UTF-8 无 BOM - 变量名含空格或特殊字符但没加引号，例如
API_KEY=abc def会被截断成abc；应写成API_KEY="abc def"或API_KEY='abc def' - 调用
getenv()前未调用$dotenv->load()，或load()抛异常但被静默吞掉（建议加try/catch并die()）
生产环境要不要提交 .env？怎么安全分发
绝对不要把真实凭证提交到 Git。标准做法是：
- 在
.gitignore中加入.env和.env.local - 提供
.env.example（含占位值，如DB_HOST=localhost），供新成员复制后修改 - 生产服务器上，通过部署脚本生成
.env（从密钥管理服务如 HashiCorp Vault / AWS Secrets Manager 拉取），或由运维手动写入（权限设为600） - 如果用 Docker，推荐用
docker run --env-file .env或 Compose 的env_file:字段，而不是在容器内再读.env文件
一个容易被忽略的点：当使用 createImmutable() 时，phpdotenv 默认不覆盖已存在的环境变量（比如系统级设置的 APP_ENV=prod）。如果你需要强制覆盖，改用 createMutable()，但多数场景下 immutable 更安全。
