FrankenPHP 已知问题排查指南不兼容扩展、musl 兼容性、Docker TLS 与 Composer 集成实战【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp本指南基于 FrankenPHP 官方已知问题Known issues文档整理系统梳理了在真实生产环境中可能遇到的高频坑点不兼容与有缺陷的 PHP 扩展、musl libc 带来的行为差异、Docker 下使用https://127.0.0.1的 TLS 证书问题、Composer 脚本调用php失败以及静态二进制缺失 CA 证书导致的 TLS/SSL 校验错误。读完本文你将掌握每个问题的成因、判断方法以及可直接落地的解决方案与验证手段。前提认知为什么 FrankenPHP 有这些特殊问题FrankenPHP 是一个基于 Caddy 构建的现代 PHP 应用服务器它将 PHP 引擎直接以线程安全ZTSZend Thread Safety模式嵌入到 Go 进程中。这一点在仓库的构建配置中有明确体现cgo.go 中设置了-DZTS1编译宏而 docs/compile.md 也强调必须使用 ZTS 变体的 libphp 才能编译 FrankenPHP。正是线程安全 常驻内存这两个特性决定了它对 PHP 扩展生态有特殊要求凡是非线程安全的扩展或在多线程下存在已知 bug 的扩展都可能在使用 FrankenPHP 时出现崩溃、死锁或行为异常。理解了这一点下文所有已知问题的成因就一目了然了。不支持的 PHP 扩展非线程安全即不兼容FrankenPHP 明确列出了以下已知不兼容的扩展扩展名不兼容原因替代方案imap非线程安全Not thread-safejavanile/php-imap2、webklex/php-imapnewrelic非线程安全Not thread-safe无实战建议如果你的应用依赖imap扩展收发邮件应优先迁移到上述纯 PHP 实现的替代库而不是在 FrankenPHP 中强行加载该扩展新 relic 的 PHP Agent 目前无法在 FrankenPHP 下工作如果需要可观测性能力可以参考仓库中关于 Metrics、Observability 的文档FrankenPHP 本身通过 Caddy 暴露了 Prometheus 格式指标从源码结构看扩展注册机制由 ext.go 中的RegisterExtension/registerExtensions完成任何扩展都以zend_module_entry形式注册进 PHP 引擎因此加载一个非线程安全的扩展风险会直接作用于整个多线程进程。有缺陷的 PHP 扩展openssl 在 musl 下的死锁除了完全不兼容的扩展外还有一类扩展能用但有坑扩展名已知问题ext-openssl使用 musl libc 时OpenSSL 扩展在高负载下可能发生死锁hang使用更主流的 GNU libc 则不会出现该问题。该 bug 由 PHP 官方跟踪实战建议如果你使用基于 Alpine 的 Docker 镜像或完全静态的二进制它们都基于 musl libc详见下文并且应用存在高并发的 TLS/加密操作如 HTTPS 出站请求、签名验证一旦观察到进程无响应应优先怀疑此问题最简单的规避方式是改用基于 Debian 的镜像或 GNU 变体的静态二进制判断当前运行时所用 libc可在容器内执行ldd --version或getconf GNU_LIBC_VERSION进行确认。get_browser()运行一段时间后性能退化get_browser()函数在长时间运行后表现不佳seems to perform badly after a while。官方给出的解决思路是因为同一 user agent 对应的浏览器能力数据是静态不变的所以应针对 user agent 做结果缓存例如使用 APCu// 以 user agent 为 key 缓存 get_browser() 的结果 $ua $_SERVER[HTTP_USER_AGENT] ?? ; $key browser_info_ . md5($ua); $info apcu_fetch($key); if ($info false) { $info get_browser($ua, true); apcu_store($key, $info, 3600); // 缓存 1 小时 }实战建议这类运行一段时间后劣化的问题在常驻进程模型FrankenPHP 的 worker 模式、long-running 请求处理中尤为常见因为它与进程生命周期直接相关除了 APCu也可以使用文件缓存或外部缓存Redis/Memcached核心原则是每个 user agent 只解析一次。独立二进制与 Alpine 镜像musl libc 的兼容性差异FrankenPHP 的完全静态二进制和Alpine 版 Docker 镜像dunglas/frankenphp:*-alpine为了缩小体积使用了 musl libc 而不是 glibc 及其同类这可能会带来一些兼容性问题。最典型的已知差异PHP 的glob()函数的GLOB_BRACE标志在 musl 环境下不可用。// 在 musl 环境下无法按预期工作 $files glob({*.php,*.html}, GLOB_BRACE);实战建议如果你的代码中使用了GLOB_BRACE例如通配多个扩展名在 Alpine 镜像或静态二进制下会失效应改用多次glob()后合并结果的方式遇到任何 libc 相关兼容性问题时官方建议优先使用 GNU 变体的静态二进制和基于 Debian 的 Docker 镜像从镜像构建看Dockerfile 使用 Debianapt 安装依赖作为基础构建与运行环境而 Alpine 变体见 alpine.Dockerfile走的是另一条 musl 构建链两者取舍明确体积 vs 兼容性。Docker 下使用https://127.0.0.1TLS 证书的坑与解法默认情况下FrankenPHP 为localhost生成 TLS 证书——这也是本地开发最简单、最推荐的方式。如果你坚持要用127.0.0.1作为访问主机名可以配置生成对应证书只需将 server name 设置为127.0.0.1。但在 Docker 环境下仅这样配置是不够的由于 Docker 自身的网络系统你会收到类似如下的 TLS 错误curl: (35) LibreSSL/3.3.6: error:1404B438:SSL routines:ST_CONNECT:tlsv1 alert internal error方案一Linux 下使用 host 网络驱动docker run \ -e SERVER_NAME127.0.0.1 \ -v $PWD:/app/public \ --network host \ dunglas/frankenphp方案二Mac / Windows 下推算容器 IPhost 网络驱动在 Mac 和 Windows 上不受支持。在这些平台上你需要推算容器将被分配的 IP 并把它加入 server names运行docker network inspect bridge查看Containers键找到当前已分配的最后一个 IP位于IPv4Address键下然后加一如果当前没有任何容器在运行那么第一个被分配的 IP 通常是172.17.0.2你的容器就是172.17.0.3把推算出的 IP 加入SERVER_NAMEdocker run \ -e SERVER_NAME127.0.0.1, 172.17.0.3 \ -v $PWD:/app/public \ -p 80:80 -p 443:443 -p 443:443/udp \ dunglas/frankenphp[!CAUTION] 务必用你的容器实际会被分配到的 IP 替换172.17.0.3。方案三开启 debug 模式定位问题如果以上方案仍无法访问https://127.0.0.1可以开启 FrankenPHP 的调试模式排查docker run \ -e CADDY_GLOBAL_OPTIONSdebug \ -e SERVER_NAME127.0.0.1 \ -v $PWD:/app/public \ -p 80:80 -p 443:443 -p 443:443/udp \ dunglas/frankenphp原理佐证从镜像内部配置看这些环境变量都是直接注入 Caddyfile 模板的。仓库自带的 caddy/frankenphp/Caddyfile 中站点块写为{$SERVER_NAME:localhost}默认值是localhost而 caddy/frankenphp/Caddyfile 中的{$CADDY_GLOBAL_OPTIONS}会把debug展开为全局 Caddy 配置选项同时 Dockerfile 暴露了80、443、443/udp端口Dockerfile 的启动命令为frankenphp run --config /etc/frankenphp/Caddyfile --adapter caddyfile。理解了这套环境变量 → Caddyfile 模板 → Caddy 全局配置的链路你就能明白为什么SERVER_NAME和CADDY_GLOBAL_OPTIONS能直接影响证书生成行为。Composer 脚本引用php失败-d参数与二进制调用问题Composer 脚本 中运行php artisan package:discover --ansi。这在 FrankenPHP 下目前会失败原因有两个Composer 不知道如何调用 FrankenPHP 二进制它期望找到的是php可执行文件Composer 可能通过-d标志向命令注入 PHP 配置项而 FrankenPHP 的 CLI 目前尚不支持-d参数。解决方案用 shell 包装脚本剥离-d参数创建一个/usr/local/bin/php包装脚本把不支持的参数剥离掉再转调 FrankenPHP#!/usr/bin/env bash # /usr/local/bin/php args($) index0 for i in $ do if [ $i -d ]; then unset args[$index] unset args[$index1] fi index$((index1)) done /usr/local/bin/frankenphp php-cli ${args[]}然后将PHP_BINARY环境变量指向该脚本并运行 Composerexport PHP_BINARY/usr/local/bin/php composer install原理佐证php-cli子命令是 FrankenPHP 官方注册的 Caddy 命令实现在 caddy/php-cli.go它注册了名为php-cli、用法为script.php [args ...]的命令核心执行逻辑cmdPHPCLI会调用frankenphp.ExecuteScriptCLI而 cli.go 中的ExecuteScriptCLI最终通过 CGO 调用frankenphp_execute_script_cli以 CLI SAPI 的方式执行 PHP 脚本并返回退出码。这个包装脚本的本质就是让 Composer 以为自己在调用标准php同时绕过 FrankenPHP 尚未支持的-d参数解析。静态二进制的 TLS/SSL 问题排查缺失 CA 证书使用静态二进制时你可能会遇到与 TLS 相关的错误例如使用 STARTTLS 发送邮件时Unable to connect with STARTTLS: stream_socket_enable_crypto(): SSL operation failed with code 5. OpenSSL Error messages: error:80000002:system library::No such file or directory error:80000002:system library::No such file or directory error:80000002:system library::No such file or directory error:0A000086:SSL routines::certificate verify failed根因静态二进制没有内置 TLS 证书OpenSSL 找不到可用的 CA 证书来校验对端因此你需要把 OpenSSL 指向本地的 CA 证书安装位置。排查步骤运行openssl_get_cert_locations()查看当前环境下 CA 证书应安装的位置并把证书存放到该位置var_dump(openssl_get_cert_locations());[!WARNING] Web 上下文和 CLI 上下文的配置可能不同。请务必在正确的上下文中执行openssl_get_cert_locations()。获取 CA 证书内容可以在 cURL 官网下载从 Mozilla 提取的 CA 证书包或者直接使用发行版自带的ca-certificates包Debian、Ubuntu、Alpine 等均提供。另一种方式是使用环境变量SSL_CERT_FILE和SSL_CERT_DIR提示 OpenSSL 去哪里查找 CA 证书# 设置 TLS 证书环境变量 export SSL_CERT_FILE/etc/ssl/certs/ca-certificates.crt export SSL_CERT_DIR/etc/ssl/certs实战建议在基于 Debian 的镜像中运行一般不会遇到此问题因为镜像内已随系统安装ca-certificates包只有完全静态的独立二进制不含系统证书库才需要显式处理上述SSL_CERT_FILE/SSL_CERT_DIR环境变量同时作用于 PHP 的 openssl 扩展与底层 OpenSSL 库配置后建议重启进程并复测 STARTTLS 等场景。总结一份快速自查清单症状首要怀疑点首选解法崩溃 / 非预期行为加载了非线程安全扩展imap、newrelic替换为纯 PHP 替代库高负载下进程卡死openssl 扩展 musl libc换 GNU/Debian 变体get_browser()变慢无缓存的重复解析按 user agent 用 APCu 缓存GLOB_BRACE不生效musl libcAlpine/静态二进制改用多次glob()合并Docker 下https://127.0.0.1报 TLS 错误容器网络 证书 host 不匹配host 网络 / 推算容器 IP 加入SERVER_NAMEComposer 脚本执行失败php找不到二进制、-d不支持使用/usr/local/bin/php包装脚本 PHP_BINARYSTARTTLS 证书校验失败静态二进制缺 CA 证书安装ca-certificates或设置SSL_CERT_FILE/SSL_CERT_DIR本指南对应的官方文档位于仓库 docs/known-issues.md英文版与多语言翻译版如 docs/cn/known-issues.md、docs/es/known-issues.md、docs/fr/known-issues.md其中英文版还额外收录了 pcov、datadog、blackfire、imagick 等扩展的已知问题可作为进阶参考。建议在部署 FrankenPHP 到生产环境前先对照本清单逐一核查你的扩展清单与运行环境可以避开绝大多数已知的坑。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考