FrankenPHP 读取 .env 失效的根本原因是其本身不解析 .env 文件，必须由 PHP 入口代码显式调用 Dotenv::load() 加载；常见问题包括未挂载文件、putenv() 被禁用、路径错误、编码含 BOM 或 OPcache 缓存干扰。
FrankenPHP 读取 .env 文件失效，根本原因在于：FrankenPHP 本身不内置 .env 解析能力，它只负责运行 PHP 脚本，而 .env 是应用层约定，必须由 PHP 项目主动加载。
这和 Laravel、Symfony 或手动引入 vlucas/phpdotenv 的逻辑一致——不是服务器（如 FrankenPHP）该做的事，而是你的 PHP 入口代码要完成的动作。
✅ FrankenPHP 环境变量加载的正确路径
FrankenPHP 启动时，会把系统级环境变量（即 docker run -e KEY=VALUE 或 env_file: 注入的变量）直接透传给 PHP 进程。但它不会自动读取项目目录下的 .env 文本文件。
所以你看到 $_ENV['APP_DEBUG'] 或 getenv('DB_HOST') 为空，通常是因为：
立即学习“PHP免费学习笔记（深入）”；
-
.env文件根本没被 PHP 代码加载； - 加载时机错误（比如在框架初始化之后才调用
Dotenv::load()）； -
putenv()被禁用（常见于 Alpine 镜像或安全加固环境），导致phpdotenv无法注入变量； -
.env文件权限不对、编码含 BOM、路径错误（例如不在项目根目录）。
? 常见失效原因与对应检查项
-
.env没被显式加载
FrankenPHP 不会自动执行任何.env解析。你必须在public/index.php（或等效入口）顶部手动初始化：$dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..'); $dotenv->load();
putenv()函数被禁用
运行php -r "var_dump(function_exists('putenv'));"，若输出false，说明putenv不可用。此时phpdotenv无法将.env中的值写入运行时环境。
✅ 替代方案：改用$_SERVER+ Web 服务器透传（如 Nginxfastcgi_param），或直接在容器启动时用-e注入。-
.env文件路径或格式错误- 必须放在项目根目录（与
composer.json同级）； - 每行严格为
KEY=VALUE，等号两边不能有空格； - 不支持嵌套语法或变量引用（如
$APP_ENV）； - 编码为 UTF-8 无 BOM，Linux 换行（LF）。
- 必须放在项目根目录（与
-
FrankenPHP 容器未挂载
.env文件
如果你用 Docker 运行 FrankenPHP，.env默认不会被自动复制进镜像。需在Dockerfile或docker-compose.yml中显式挂载：volumes: - ./.env:/app/.env
否则即使代码写了
load()，也会因文件不存在而静默失败。 OPcache 或配置缓存干扰
修改.env后，若 PHP 启用了 OPcache 且未配置opcache.validate_timestamps=1，旧变量可能仍被缓存。
✅ 清除 OPcache：php -r "opcache_reset();"，或重启 FrankenPHP 进程。
? 补充：FrankenPHP 下更推荐的做法
由于 FrankenPHP 基于 SAPI（类似 CLI/FPM），它天然支持系统环境变量。生产环境建议：
- 完全弃用
.env文件，改用容器-e或env_file注入； - 在 PHP 中统一使用
getenv('KEY')（而非依赖$_ENV，因其受variables_order影响）； - 若必须保留
.env，确保phpdotenv版本 ≥ 5.6，并在index.php最早位置加载（早于任何框架初始化）。
不复杂但容易忽略。
