MacOS 系统使用 Homebrew 安装 FrankenPHP 步骤-php教程-PHP中文网

homebrew安装frankenphp需先配置好php 8.3+运行时：①brew install php@8.3并brew link --force php@8.3确保php -v可用且which php指向homebrew路径；②确认php.ini中extension_dir为/opt/homebrew/lib/php/20230831并启用opcache等扩展；③再brew install frankenphp，最后用worker示例验证http响应。

macos 系统使用 homebrew 安装 frankenphp 步骤

Homebrew 安装 FrankenPHP 在 macOS 上是可行的，但必须注意：它不提供 PHP 运行时，只提供 FrankenPHP 二进制本身；你得自己配好系统级或 Homebrew 管理的 PHP（8.3+）并确保 php 命令可用。

为什么 brew install frankenphp 会失败或启动报错

Homebrew 的 frankenphp 公式（截至 2026 年 10 月）是「runtime-agnostic」的：它只打包 FrankenPHP 主程序，不捆绑 PHP 解释器。常见报错如：

frankenphp: error while loading shared libraries: libphp.so: cannot open shared object file（Linux 风格错误，macOS 实际报 dlopen(libphp.dylib): image not found）
PHP binary not found at /usr/bin/php 或类似路径提示

根本原因是 FrankenPHP 启动时默认查找系统 php，而 Homebrew 安装的 PHP（如 php@8.3）路径不在 /usr/bin，且未链接到全局 php 命令。

正确安装顺序：先 PHP，再 FrankenPHP

Homebrew 要求你显式安装 PHP 并确保 php 可执行命令就绪——FrankenPHP 不会帮你做这一步。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

运行 brew install php@8.3（推荐 8.3 或 8.4；8.5 尚未进入 Homebrew 核心仓库）
执行 brew link --force php@8.3，让 php、php-config 等命令进入 $PATH
验证：php -v 应输出版本号，且 which php 返回类似 /opt/homebrew/bin/php
最后安装：brew install frankenphp

启动 FrankenPHP 前必须确认 PHP 扩展路径

FrankenPHP 内置的 PHP 加载逻辑依赖 php.ini 中的 extension_dir 设置。Homebrew 的 PHP 默认扩展目录是：

/opt/homebrew/lib/php/20230831

如果你用的是 php@8.3，这个路径里的 .so 文件（如 opcache.so、curl.so）必须存在且可读。常见问题：

运行 frankenphp worker 报 Failed loading extension 'opcache' → 检查 php -m | grep opcache 是否启用；若没启用，编辑 $(php --ini | grep "Loaded Configuration File" | cut -d' ' -f4)，取消注释 zend_extension=opcache
扩展目录权限被 SIP 限制（M1/M2/M3 Mac）→ 不要手动改 /opt/homebrew/lib/php/... 权限，而是用 pecl install 或 brew install php@8.3-xdebug 等方式安装扩展

验证是否真正可用：跑一个最小 worker 示例

别只测 frankenphp --version，那只是二进制存在。真正关键的是能否加载 PHP 并执行代码：

新建 worker.php：

<?php use FrankenPHP\FrankenPHP;

FrankenPHP::setWorkerScript(__FILE__);
FrankenPHP::onRequest(function () {
    return new \React\Http\Message\Response(
        200,
        ['Content-Type' => 'text/plain'],
        "OK\n"
    );
});