Hyperf中.env加载失败主因是加载时机过早、路径错误、权限/编码异常、语法不合规或PHP未启用$_ENV；修复需确保绝对路径加载、语法规范、容器初始化后调用env()，并重启进程生效。
Hyperf 启动失败，.env 配置错误是高频诱因之一，但问题往往不单是“文件写错了”，而是加载时机、路径、权限、语法、缓存等环节共同失效。修复需系统排查，而非盲目改值。
确认 .env 是否被真正加载
Hyperf 默认只加载项目根目录下的 .env，且依赖 hyperf/framework 内置的 DotenvLoader。常见未加载原因：
- 文件不存在 → Hyperf 3.1 已修复“无
.env导致重启失败”问题，但若配置中硬依赖环境变量（如数据库地址），仍会启动卡在初始化阶段 - 路径错误 →
Dotenv::createImmutable(__DIR__)在协程中可能因工作目录变动失效；应改用绝对路径：Dotenv::createImmutable(BASE_PATH) - 权限或编码问题 → Windows 下 Git Bash 创建的
.env若含 CRLF 换行符，部分vlucas/phpdotenv版本无法解析；建议用 Unix 换行（LF）并确保文件可读 - PHP
variables_order缺失E→ 运行php -i | grep variables_order，输出必须含E（即启用$_ENV），否则env()函数始终返回false
检查 .env 语法是否合规
Hyperf 使用标准 phpdotenv 规则，以下写法均会导致解析失败：
- 变量名含空格或特殊字符但未加引号：
API_KEY=abc def→ 应写为API_KEY="abc def" - 使用
export前缀：export DB_HOST=127.0.0.1→export是 shell 语法，Hyperf 不识别，直接删掉 - 值内含
#未转义：SECRET=ab#cde中#被当注释 → 改为SECRET="ab#cde" - 键名含点号或连字符：
REDIS.HOST=localhost或APP-NAME=myapp→ 推荐改用下划线：REDIS_HOST=localhost、APP_NAME=myapp
验证 env() 调用是否在正确时机执行
在 config/autoload/*.php 中直接调用 env('DB_HOST') 极易返回 false，因为此时 .env 尚未加载。典型表现：配置 fallback 到默认值，但实际环境变量没生效。
- ✅ 正确做法：将
env()调用推迟到容器初始化后，例如在Command、Listener或ServiceProvider::boot()中使用 - ⚠️ 临时绕过：在
bin/hyperf.php顶部手动加载（需确保路径和phpdotenv版本兼容）：(new \Dotenv\Dotenv(BASE_PATH))->load();
修改后必须重启进程，缓存不自动刷新
Hyperf 的 cache:clear 或 gen:publish 只清配置数组缓存（即 config/autoload/ 返回值），不影响 getenv() 运行时状态。
- CLI 启动服务：必须
kill当前进程再php bin/hyperf.php start - Docker 环境：重建镜像或重启容器，不能仅
docker exec进去改文件 - 若启用 OPcache，极少数情况旧逻辑被缓存，可临时
opcache_reset()或重启 PHP-FPM/Swoole 进程
不复杂但容易忽略
