FrankenPHP中$_SERVER['DOCUMENT_ROOT']不可靠，因其不自动注入Caddyfile的root值，导致路径拼接失败；应改用__DIR__或Composer加载，显式配置Caddy root与路由，并强制设置session等路径。
会失效，尤其是基于 $_SERVER 或文件系统绝对路径的硬编码。 FrankenPHP 的运行模型和传统 FPM/Nginx 完全不同，路径上下文、请求生命周期、甚至 PHP 进程的启动方式都变了，写死的路径很容易“找不到地方”。
为什么 $_SERVER['DOCUMENT_ROOT'] 在 FrankenPHP 里不可靠
FrankenPHP 不依赖 Apache 或 Nginx 的 DocumentRoot 指令，它通过 Caddyfile 的 root 指令定义服务根目录，但这个值不会自动注入到 $_SERVER['DOCUMENT_ROOT'] 中——该超全局变量在 FrankenPHP 下是空的、未设置的，或沿用旧环境残留值。
- 直接读
$_SERVER['DOCUMENT_ROOT']得到''或null，include或require会失败 - 很多老项目用它拼接配置路径，比如
require $_SERVER['DOCUMENT_ROOT'].'/config/database.php';，迁过来直接报Warning: require(): open_basedir restriction...或failed to open stream - 解决方法不是“修复
$_SERVER”，而是绕过它：用__DIR__或dirname(__FILE__)向上追溯，或者统一用 Composer 自动加载机制
静态资源路径（如 public/、storage/）要重定义 root 和别名
FrankenPHP 默认把当前工作目录当根，但 Laravel/Symfony 等框架默认期望 public/ 是 Web 可访问入口。如果 Caddyfile 里没显式声明 root，它就会把项目根（含 vendor/、app/）暴露出去，既不安全，也导致 CSS/JS 404。
- Caddyfile 必须写明：
root * public/（星号表示匹配所有主机） - 若需访问
storage/app/public/下的软链资源，得加handle /storage/* { root * storage/app/public/ }显式路由 - 别指望
public_path()或storage_path()返回的路径能直接用于 Web 访问——它们返回的是文件系统路径，不是 URL 路径；URL 路径由 Caddy 的路由规则决定
session、cache、logs 等运行时目录权限和路径必须显式配置
FrankenPHP 进程以当前用户身份运行（非 www-data），且不读取系统级 php.ini 的默认路径。像 session.save_path 这类配置，如果代码里没调用 ini_set()，就会 fallback 到 PHP 编译时的默认值（如 /tmp），而 FrankenPHP 二进制可能没权限写入。
立即学习“PHP免费学习笔记（深入）”；
- 检查实际生效路径：
php -r "echo ini_get('session.save_path');"，确认是否可写（is_writable()） - 推荐在
bootstrap/app.php开头强制设置：ini_set('session.save_path', __DIR__.'/../storage/framework/sessions'); - 同理处理
opcache.file_cache、error_log、upload_tmp_dir—— 所有依赖文件系统路径的 INI 项，都不能靠“默认”
最麻烦的不是路径本身，而是路径逻辑混在框架生命周期早期（比如服务提供者注册阶段）被调用，而 FrankenPHP 的常驻进程会让这些路径只解析一次。一旦第一次错了，后续所有请求都沿用错误路径，连重启都未必刷新——得删掉 worker 进程或清空 opcache 才能重试。
