FrankenPHP 通过 frankenphp run 一条命令即可启动带 HTTPS、HTTP/2/3、静态文件服务和 PHP 执行能力的生产级服务,前提是存在 Caddyfile 且域名可解析、端口可用。

FrankenPHP 不需要“配置完再启动”,frankenphp run 一条命令就能跑起带 HTTPS、HTTP/2、静态文件服务和 PHP 执行能力的生产级服务——前提是当前目录有 Caddyfile,且域名可解析、端口未被占用。
为什么 frankenphp run 能直接上生产?
它不是开发服务器,而是把 Caddy + 嵌入式 PHP 运行时 + ACME 客户端打包进单个进程。只要系统能连外网、有 80/443 端口权限、域名 DNS 已生效,它就会自动:申请 Let’s Encrypt 证书、启用 TLS 1.3、开启 HTTP/2 和 HTTP/3、预加载 OPcache、绑定 php_server 处理器——全部无需手动干预。
常见错误现象:listen tcp :443: bind: permission denied(非 root 用户无法监听 443)、acme: error: 400 :: POST :: https://acme-v02.api.letsencrypt.org/acme/new-order :: urn:ietf:params:acme:error:unauthorized :: Invalid response from ...(DNS 未生效或防火墙拦截 80 端口)。
- 必须用 root 或
sudo启动才能监听 80/443;若只想测试,改用SERVER_NAME=:8080环境变量避开权限问题 - DNS A 记录变更后需等待全球生效(通常 1–2 小时),期间可用
curl -v http://yourdomain.com看是否返回 301 跳转到 HTTPS - 本地开发想跳过 HTTPS,直接在
Caddyfile里写http://localhost或:8080,Caddy 就不会触发 ACME 流程
Caddyfile 最小可行配置长什么样?
FrankenPHP 默认只认当前目录的 Caddyfile,没这个文件就报错退出。最简但可上线的配置只有三行:
{ frankenphp { num_threads auto } }
yourdomain.com {
root * /app/public
php_server
}
注意点:
-
root必须显式声明,否则静态文件(如/favicon.ico)会 404;Laravel/Symfony 项目一般设为/app/public,ThinkPHP 可能是/app/public或/app/web -
php_server指令不能写成php或fastcgi,后者是 Nginx/FPM 语法,FrankenPHP 会忽略 - 如果项目入口不是
index.php(比如用了router.php),得加php_server /router.php显式指定
worker 模式怎么开?为什么别急着开
worker 模式让 PHP 进程常驻内存,跳过每次请求重复加载框架、重建容器的开销,对 Laravel/Symfony 类应用提升明显。但它不是默认开启的,得在 Caddyfile 里加 worker 指令:
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
yourdomain.com {
root * /app/public
php_server {
worker /app/worker.php
}
}
容易踩的坑:
-
/app/worker.php必须存在且返回一个实现了FrankenPHP\WorkerInterface的类实例,官方示例里是new App\Worker();直接放个空文件会启动失败 - worker 模式下,
$_SERVER和$_GET不再自动注入,得靠$request->getParsedBody()读取数据,传统$_POST写法会失效 - 开发阶段别开 worker:代码修改后要
kill -SIGUSR2重载进程,不如 classic 模式改完刷新即生效来得直观
Docker 部署时 SERVER_NAME 环境变量怎么设?
Docker 官方镜像(dunglas/frankenphp)依赖 SERVER_NAME 决定监听哪个域名。设错会导致 HTTPS 申请失败或 502 错误。
正确做法:
- HTTPS 场景:设为你的公网域名,例如
SERVER_NAME=api.example.com;多个域名用逗号分隔:SERVER_NAME=example.com,www.example.com - 仅 HTTP 测试:设为
SERVER_NAME=:80,此时 Caddy 不走 ACME,也不会尝试 HTTPS 重定向 - 本地 Docker Compose 中不要写
environment: SERVER_NAME: localhost——Caddy 会尝试给localhost申请证书,必然失败;应改用SERVER_NAME=:8080并映射端口
真正麻烦的是多租户或子路径部署:FrankenPHP 目前不支持 location /api { php_server } 这种嵌套路由,所有 PHP 请求必须落在根路径或显式配置的子域名下。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










