frankenphp安装方式分三种:docker镜像(跨平台,仅需宿主机支持docker)、linux静态二进制(x86_64/aarch64,musl静态链接,需手动放行udp 443)、windows原生版(22h2+,免wsl,支持全特性)。

安装 FrankenPHP 主要分三种方式:Docker 镜像、本地静态二进制、Windows 原生版。不同方式对系统的要求差异明显,关键不在于“操作系统版本号”,而在于运行环境是否匹配其底层依赖。
Docker 方式:最低门槛,跨平台通用
只要宿主机能运行 Docker Desktop(macOS/Windows)或 Docker Engine(Linux),就满足基础要求:
- macOS:Intel 或 Apple Silicon,Docker Desktop ≥ 4.18(含 WSL2 后端支持)
- Windows:Windows 10/11 Pro/Enterprise(需启用 WSL2),或 Windows Server 2016+(Docker EE)
- Linux:内核 ≥ 3.10,已安装 Docker Engine(无需额外 PHP、Composer 或扩展)
- 内存建议 ≥ 2 GB(Caddy 自动管理 HTTPS 证书会占用临时空间)
本地静态二进制:仅限 Linux x86_64 / aarch64
必须是 musl libc 环境生成的静态文件,因此不能在 glibc 系统(如 Ubuntu、CentOS、Debian)上直接编译,但可在其上运行:
- 支持平台:Linux x86_64(主流云服务器)、Linux aarch64(树莓派 5、AWS Graviton)
- 不支持 macOS 或 Windows 直接运行该二进制(即使 Apple Silicon 也不行)
- 验证方法:下载后执行
file ./frankenphp,输出含 statically linked 才有效;若显示 dynamically linked,说明构建环境错误 - 防火墙需手动放行 UDP 443(HTTP/3 必需),Docker 版本自动处理,本地版需自行配置
Windows 原生版:正式支持,无需 WSL
自 2026 年起,FrankenPHP 提供官方 Windows 构建,基于 MSVC 工具链,与 Go 的 CGO 兼容问题已解决:
- 系统要求:Windows 10 22H2 或更高版本,Windows Server 2022+
- 支持全部核心特性:Worker Mode、Hot Reloading、HTTP/3、自动 HTTPS(使用本地证书)
- 性能实测优于传统 Nginx+PHP-FPM(同一台 Windows Server 上提升超 260%)
- 注意:生产环境若追求极限吞吐,仍推荐 Linux;Windows 更适合开发、内网部署或边缘轻量场景
特别提醒:静态构建机器 ≠ 运行机器
如果你要自己构建静态二进制(例如打包 Laravel 应用),构建过程必须使用 dunglas/frankenphp:static-builder-musl 镜像:
- 该镜像是唯一可靠方式,基于 Alpine Linux + musl libc
- 宿主机只需能运行 Docker,无需装 PHP、gcc、make 等任何构建工具
- 扩展必须在构建时显式安装(如
RUN docker-php-ext-install pdo_mysql opcache),运行时无法动态加载 - 构建产物只能部署到同架构 Linux(x86_64/aarch64),不可用于 macOS/Windows 运行
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!











