FrankenPHP独立二进制不支持运行时加载Caddy模块，所有模块均静态编译进二进制；如需新增模块，必须克隆源码、修改注册逻辑并重新构建，无法通过-plugin参数、环境变量或挂载方式动态扩展。
FrankenPHP 二进制不支持运行时加载 Caddy 模块
FrankenPHP 的独立二进制（如 frankenphp）是静态链接的 Go 程序，它把 Caddy 核心和已启用的模块（如 http.handlers.php_server、http.reverse_proxy）全部编译进去了。你不能像 Caddy 官方二进制那样用 -plugins 参数动态注入新模块，也没有 caddy adapt --with 这类机制可用。
要加模块，必须从源码重新构建二进制
新增 Caddy 模块的唯一可靠路径是：克隆 FrankenPHP 仓库 → 修改 main.go 或插件注册逻辑 → go build 生成新二进制。常见操作包括：
- 在
cmd/frankenphp/main.go的init()函数里调用目标模块的Register()，例如：caddycmd.RegisterCommand(caddycmd.Command{...})或httpcaddyfile.RegisterHandlerDirective("my_handler", ...) - 如果模块本身依赖第三方 Go 包（比如
github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy），需确保go.mod已声明并go mod tidy - 构建命令建议显式指定 CGO 和平台：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o frankenphp ./cmd/frankenphp（禁用 CGO 可避免 libc 兼容问题）
别指望 Docker 镜像或 install-php-extensions 帮上忙
官方镜像 dunglas/frankenphp 和所有预编译二进制都只含固定模块集。以下方式完全无效：
-
install-php-extensions只管 PHP 扩展，对 Caddy 模块零作用 - Docker
COPY或挂载新模块文件到容器里——Caddy 不会扫描目录加载 .so - 设环境变量如
CADDY_MODULES—— FrankenPHP 未实现该机制 - 试图用
caddy list-modules查看——该命令不在 FrankenPHP 二进制中
替代方案：用 Caddyfile + reverse_proxy 绕过限制
如果你只是想用某个 FrankenPHP 原生不带的 Caddy 功能（比如 http.handlers.cache 或自定义认证），更现实的做法是：
立即学习“PHP免费学习笔记（深入）”；
- 保持 FrankenPHP 仅做 PHP worker（监听
127.0.0.1:8080） - 另起一个标准 Caddy 实例（用官方二进制），在它的
Caddyfile中用reverse_proxy转发 PHP 请求过去 - 这样你就能自由启用任意 Caddy 模块，而 FrankenPHP 只专注执行 PHP
- 注意：此时健康检查、日志聚合、TLS 终止等都由外层 Caddy 控制，FrankenPHP 退为纯后端进程
模块扩展这件事，本质上是在 FrankenPHP 的“集成度”和“灵活性”之间做取舍——选原生二进制就得接受它的模块边界；要自由，就得拆开用。
