frankenphp php-server 启动时必须显式指定 --document-root（如 public/），否则因无默认根目录而报404或空白页；它仅提供PHP执行层，不支持HTTPS/HTTP/3，需搭配Caddyfile使用frankenphp命令才能启用完整Web功能。
frankenphp php-server 启动时必须指定 document-root
直接运行 frankenphp php-server 会报错或返回 404，因为 FrankenPHP 不像传统服务器那样默认猜路径。它要求你明确告诉它“网站根目录在哪”——通常是 Laravel/Symfony 的 public/ 目录。
常见错误现象：404 Not Found、file not found: index.php、终端无响应但浏览器空白页。
- 正确命令是：
frankenphp php-server --document-root public/ - 如果项目结构不同（比如入口在
web/或htdocs/），把public/换成对应路径即可 - 端口默认是
:8000，可用--addr :8080修改；本地测试建议避开已占端口（如被 Vite、Python HTTP server 占用） - 不支持 HTTPS / HTTP/3 —— 这个模式只是纯 PHP 执行层，TLS 和协议升级要靠 Caddy 或前置代理
用 Caddyfile 启动才支持 HTTPS 和 HTTP/3
想开箱即用 HTTPS（自动证书）、HTTP/2、HTTP/3，就不能只用 php-server 子命令，得搭配 Caddyfile 启动。FrankenPHP 的独立二进制内置了 Caddy，只要配置文件存在，它就会自动接管 HTTP 层。
操作很简单：
立即学习“PHP免费学习笔记（深入）”；
- 在项目根目录新建文件
Caddyfile - 内容至少包含三行：
{ frankenphp }、域名块（如localhost）、root public/和php_server - 然后直接运行
frankenphp（不带任何子命令）
示例最小配置：
localhost {
root * public/
php_server
}启动后访问 https://localhost 就能拿到自签名证书（首次需手动接受），https://localhost:443 默认走 HTTP/2，UDP 443 自动启用 HTTP/3。
启动失败常见原因和排查点
不是命令写错，就是环境或路径卡住。重点盯这几个地方：
-
public/index.php不存在或权限不对（Linux/macOS 下检查是否可读，Windows 注意换行符） -
.env里APP_DEBUG=true且没装symfony/var-dumper或laravel/framework依赖，会导致启动时 fatal error - PHP 扩展缺失：FrankenPHP 静态二进制默认启用
pdo_sqlite、ctype等基础扩展，但如果你代码用了ext-memcached或ext-redis，得用--php-ini指定含extension=的配置文件 - Mac 上 Gatekeeper 可能拦截：首次运行提示“无法验证开发者”，右键 → “打开”绕过一次即可
单二进制打包后怎么启动
用 frankenphp build 打出来的文件（比如叫 myapp），它本身就是一个完整服务，不需要再配 Caddyfile 或传参数。
启动方式极简：
- Linux/macOS：
chmod +x myapp && ./myapp - Windows：
myapp.exe双击或命令行执行 - 它默认监听
https://localhost（自动签发证书），HTTP 重定向到 HTTPS；如需纯 HTTP，加--http-only参数 - 注意：这个二进制已经固化了
server-name（构建时用--server-name指定），不能临时改域名；想换就得重构建
最易忽略的是：打包后的二进制不读取项目目录里的 .env，所有环境变量必须在构建时注入（通过 --env）或运行时用 APP_ENV=prod ./myapp 方式传入。
