FrankenPHP v1.2.0 在 macOS 上启动 PHP 项目必须显式指定 --root 指向含 index.php 和 Caddyfile 的目录，否则默认以当前工作目录为根导致 404 或 .env 加载失败；轻量启动可选 --script index.php 或 FRANKENPHP_ROOT 环境变量。
在 macOS 上用 FrankenPHP v1.2.0 启动 PHP 项目时，必须显式指定项目根目录，否则它会默认以当前工作目录为根——而这个目录往往不是你的应用入口所在，导致路由 404、静态文件 404 或 .env 文件读取失败。
确认 FrankenPHP 已安装并可用
打开终端，执行 frankenphp version。若返回类似 v1.2.0 (built with Caddy v2.8.4, PHP 8.5.0) 的输出，说明已正确安装；若提示 command not found，请先运行 curl https://frankenphp.dev/install.sh | sh 安装。
用 --root 指定项目根目录启动
进入你的 PHP 项目所在路径（即包含 index.php 和 Caddyfile 的目录），执行：
frankenphp run --root ./
立即学习“PHP免费学习笔记（深入）”；
这会把当前目录设为项目根，并自动加载同级的 Caddyfile。如果你的项目结构是 /Users/me/myapp/，且 index.php 在该目录下，就直接在这个路径下运行命令。
【注意：--root 必须指向包含 index.php 的目录，不能指向其父目录或子目录】
不依赖 Caddyfile 的轻量启动方式
方法一：直接绑定端口并指定入口脚本
frankenphp run --root /path/to/myapp --addr :8080 --script index.php
这跳过 Caddyfile 解析，强制将所有请求转发给 index.php，适合 Laravel、Symfony 等前端控制器架构。路径 /path/to/myapp 必须绝对路径，相对路径（如 ./myapp）在此模式下可能解析异常。
方法二：用环境变量覆盖根目录（仅限开发调试）
FRANKENPHP_ROOT=/path/to/myapp frankenphp run --addr :8080
该变量优先级高于命令行参数，但仅在未使用 --root 时生效；一旦同时出现，--root 始终胜出。此方式适合写入 Makefile 或 shell alias，避免反复输入长路径。
验证根目录是否生效
第一步：启动后访问 http://localhost:8080，观察是否正常加载首页；
第二步：在浏览器开发者工具 Network 面板中查看任意 CSS/JS 请求的响应头，确认 X-Powered-By 存在且无 404；
第三步：在终端中按 Ctrl+C 停止服务，然后执行 frankenphp run --root /tmp --addr :8081（指定一个空目录），再访问 http://localhost:8081 —— 此时应返回 404 或 “No index file found”，证明 --root 确实控制了文档根。
