frankenphp在ubuntu 24.04上无法通过apt安装，需采用官方二进制（推荐生产环境）或docker（适合开发/ci）方式部署；二进制部署需正确配置systemd unit文件（含workingdirectory和frankenphp_server_name环境变量），docker则须指定v1.0镜像标签并挂载/public路径。
FrankenPHP 在 Ubuntu 24.04 上不是通过 apt 官方源安装的，它没有 Debian 包，也不进 Ubuntu 主仓库。直接用系统包管理器装不到，硬装会失败或版本严重滞后。
你得走二进制分发或 Docker 这两条路——前者轻量、适合服务器裸机；后者隔离强、适合开发/测试/CI。下面按实际部署场景拆解。
用官方二进制直接部署（推荐用于生产裸机）
这是最干净、最可控的方式，不依赖 PHP-FPM、不污染系统 PHP 环境，整个服务就一个可执行文件 + 配置文件。
- 下载最新稳定版二进制（截至 2026 年 10 月，
FrankenPHP 1.0已发布）：curl -L https://github.com/dunglas/frankenphp/releases/download/v1.0.0/frankenphp_1.0.0_linux_amd64.tar.gz | tar xz
- 把
frankenphp可执行文件放进系统路径：sudo install frankenphp /usr/local/bin/
- 确认能跑：
frankenphp version
输出应含v1.0.0 - 准备最小
Caddyfile（比如放在/etc/frankenphp/Caddyfile）：localhost:8000 { root * /var/www/html php_server file_server }注意：不用写fastcgi_pass，php_server是 FrankenPHP 自带指令 - 启动服务（建议用 systemd）：
sudo systemctl start --now frankenphp@/etc/frankenphp/Caddyfile
（需先写好对应 unit 文件，见下一条）
systemd unit 文件怎么写才不崩
FrankenPHP 没自带 systemd 集成，自己写 unit 时最容易漏掉两个关键点：工作目录没设、环境变量缺失。一旦出错，journalctl -u frankenphp 里只报 exit code 1，毫无线索。
- 创建
/etc/systemd/system/frankenphp@.service：[Unit] Description=FrankenPHP %i After=network.target[Service] Type=simple User=www-data Group=www-data WorkingDirectory=/var/www/html Environment="FRANKENPHP_SERVER_NAME=localhost:8000" ExecStart=/usr/local/bin/frankenphp run --config %i Restart=always RestartSec=5[Install] WantedBy=multi-user.target
- 关键点：
WorkingDirectory必须设，否则phpinfo()里的DOCUMENT_ROOT会错；FRANKENPHP_SERVER_NAME要显式传，否则 HTTPS 自动证书申请可能失败 - 启用并启动：
sudo systemctl daemon-reload sudo systemctl enable --now "frankenphp@/etc/frankenphp/Caddyfile"
Docker 部署（适合快速验证或 CI/CD）
如果你已经在用 Docker，别折腾二进制。官方镜像 dunglas/frankenphp 已全面支持 v1.0，但要注意 tag 命名规则变了——不再用 latest，必须指定 v1.0。
- 拉镜像：
docker pull dunglas/frankenphp:v1.0
- 运行（挂载你的 PHP 项目）：
docker run -p 8000:80 \ -v $(pwd)/public:/app/public \ -e SERVER_NAME=localhost:8000 \ dunglas/frankenphp:v1.0
注意：/app/public是 FrankenPHP 默认 DocumentRoot，别挂错路径 - 如果项目是 Laravel/Symfony，要额外加环境变量：
-e APP_ENV=production -e APP_DEBUG=false
否则调试信息会暴露
常见错误和绕过方式
装完跑不起来？90% 出在权限、路径、扩展三处。别急着重装。
-
PHP extension "mbstring" is not loaded：FrankenPHP 不复用系统 PHP 扩展，它自带精简版运行时。某些框架强制检查扩展，这时要在Caddyfile里加：php_server { extensions mbstring,xml,ctype } - 访问返回 404，但静态文件正常：说明
php_server指令没生效，检查 Caddyfile 是否在root块内，且php_server没被其他route规则覆盖 - HTTPS 自动证书失败，日志里有
acme: error: 429：Let’s Encrypt 限流了，临时改SERVER_NAME为:80先跑 HTTP，等调试完再切回域名 -
frankenphp命令找不到：确认/usr/local/bin在$PATH里，普通用户执行echo $PATH看一眼，别只在 root 下装却用普通用户启
FrankenPHP 的核心价值不在“多快”，而在“少一层胶水”。一旦你开始调 php-fpm.sock 权限、改 pm.max_children、同步 Nginx 和 PHP 的 upload_max_filesize，就该意识到：问题不是 PHP 慢，是配置链太长。v1.0 把这事压进一个二进制，但代价是你得亲手管好它的入口点——Caddyfile 就是唯一真相，别再找别的配置文件了。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
