Webman 默认不加载 .env 文件，需手动集成 vlucas/phpdotenv：在 start.php 顶部调用 Dotenv::createImmutable(__DIR__)->load()，确保早于任何 config() 调用；.phar 场景改用 BASE_PATH 加载；容器部署需确认 variables_order 包含 E。
Webman 的 .env 文件默认完全不生效，不是“没配对”，而是框架压根不加载——所有读取为空、配置不变、env() 返回 false 或默认值，根源都在这一条。
为什么 .env 写对了也读不到
Webman（包括底层 Workerman）没有内置 .env 解析逻辑。你调用的 env() 函数，要么来自 majie721/webmanenv 插件，要么是你自己引入的 vlucas/phpdotenv。框架启动流程里根本没这一环。
- 常见错误现象：
config('app.debug')始终返回false，不随.env中APP_DEBUG=true变化 -
getenv('DB_HOST')返回false或null，数据库连接直接报错 - 打包成
.phar后彻底失效——.env被排除在外，且运行时未重新加载 - 在容器中
docker run --env-file .env传了变量，但 PHP 仍读不到，说明框架层没走getenv()路径，或variables_order缺少E
必须在 start.php 顶部手动加载 vlucas/phpdotenv
这是最通用、兼容性最好的方式，适配 Webman v1.x / v2.x 和 .phar 场景。
- 执行
composer require vlucas/phpdotenv - 在
start.php最顶部（必须在任何config()调用之前）加入：
use Dotenv\Dotenv; $dotenv = Dotenv::createImmutable(__DIR__); $dotenv->load();
-
__DIR__表示从项目根目录找.env；若文件放在别处（如config/.env），需传入完整路径：Dotenv::createImmutable(__DIR__ . '/config') - 不要用
createUnsafeImmutable()，它会覆盖已存在的系统环境变量，CI/容器部署时容易出问题 - 开发期可加
->safeLoad()避免因.env缺失报错，但上线前建议确保文件存在
.phar 打包后 .env 失效怎么办
.phar 默认不包含外部文件，.env 不在包内，且 __DIR__ 指向的是 PHAR 内部路径，无法访问宿主机上的 .env。
立即学习“PHP免费学习笔记（深入）”；
- 改用
BASE_PATH外部路径加载：在config/bootstrap.php顶部（早于任何config/*.php加载）添加：
if (file_exists(BASE_PATH . '/.env')) {
putenv("APP_ENV=local");
(new \Dotenv\Dotenv(BASE_PATH))->load();
}
- 务必验证
BASE_PATH指向实际磁盘上的项目根目录（非 PHAR 内部路径），可用var_dump(BASE_PATH)确认 - 更彻底的方案是「静态注入」：将
.env中的关键变量值直接写入 PHP 配置数组（如config/database.php），绕过运行时读取逻辑，适合生产环境禁用动态加载的场景
容器或命令行传参覆盖 .env 值的正确顺序
这不是替换整个文件，而是运行时覆盖单个变量。关键在于：参数要进 putenv()，且必须早于 Dotenv::load() 执行。
- 正确顺序（写在
start.php开头）：
foreach ($argv as $i => $arg) {
if ($arg === '-e' && isset($argv[$i + 1]) && str_contains($argv[$i + 1], '=')) {
putenv($argv[$i + 1]);
}
}
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();
- 此时
Dotenv会跳过已存在的环境变量，只加载缺失项 - 容器中请确保使用
-e DB_HOST=localhost或--env-file .env启动，并检查php.ini中variables_order包含E（即设为"EGPCS"）
最容易被忽略的是加载时机——Dotenv::load() 必须在所有 config() 调用之前，哪怕只差一行，配置就可能已经固化，后续 env() 就读不到新值了。
