FrankenPHP离线部署需在构建阶段用docker-php-ext-install静态编译启用扩展（如pdo_mysql、curl），因其不支持运行时动态加载；默认仅含核心扩展，缺失则报“Class not found”等错，须用frankenphp check验证。
FrankenPHP 二进制本身是静态链接的，frankenphp 主程序在 Linux x86_64 上不依赖系统 glibc 或 PHP 扩展动态库——但你的 PHP 应用仍可能因扩展缺失而启动失败，尤其在离线环境里。
为什么 frankenphp 启动报 “Class not found” 或 “extension missing”
常见错误不是 FrankenPHP 自身缺依赖，而是你应用代码调用了未启用的 PHP 扩展（如 pdo_mysql、curl、mbstring），而 FrankenPHP 默认只启用核心扩展（json、phar、openssl 等）。离线环境下无法用 apt install php-mbstring 补救，必须提前内置。
- 错误现象示例：
PHP Fatal error: Uncaught Error: Class 'PDO' not found或Call to undefined function curl_init() - 根本原因：FrankenPHP 的 PHP 运行时是编译时决定的，不是运行时动态加载 .so 文件；它不读取系统
/etc/php/*/mods-available/ - 离线场景下，你无法通过包管理器安装扩展，只能靠构建阶段显式启用
构建时启用扩展：用 docker-php-ext-install 静态编译进二进制
官方 frankenphp:static-builder-musl 镜像提供了一套基于 Alpine + musl 的构建环境，支持在构建阶段编译常用扩展进最终二进制。这是离线部署唯一可靠的方式。
- 必须在
Dockerfile的构建阶段执行：docker-php-ext-install pdo_mysql mbstring curl opcache - 注意：不能装
gd或imagick这类依赖外部系统库的扩展，除非你同时在 builder 镜像中apk add对应的 dev 包（这会破坏“离线可用”前提） - 扩展启用后，
phpinfo()里能看到对应模块，且get_loaded_extensions()返回列表包含它们 - 验证方式：构建完镜像后，进入容器执行
frankenphp eval "var_dump(extension_loaded('pdo_mysql'));"
composer install --no-dev 不解决扩展缺失问题
很多人误以为只要 Composer 安装了生产依赖，扩展就自动有了。事实相反：composer 只管 PHP 包，不管 PHP 扩展。即使 composer.json 声明了 "ext-pdo": "*"，FrankenPHP 也不会帮你装扩展——它只会在启动时检查，发现没加载就直接报错退出。
立即学习“PHP免费学习笔记（深入）”；
-
composer install --no-dev --ignore-platform-reqs是必须的，但它掩盖不了扩展缺失的事实 -
--ignore-platform-reqs只跳过 Composer 对扩展存在的检查，不等于扩展真存在 - 真正起作用的是构建时的
docker-php-ext-install，不是运行时的 Composer 参数
离线部署前最后一步：用 frankenphp check 验证扩展可用性
别等上线才看到白屏。FrankenPHP 提供了 check 子命令，可模拟启动流程并报告扩展和配置问题。
- 在构建完成的镜像或打包后的二进制目录里执行：
frankenphp check --config Caddyfile - 它会加载
Caddyfile，解析 PHP 目录，尝试初始化所有声明的扩展，并输出缺失项清单 - 如果提示
Extension "zip" is not loaded，说明你漏了docker-php-ext-install zip - 这个命令不启动 HTTP 服务，纯静态检查，适合 CI/CD 流水线集成
离线环境最易被忽略的一点：FrankenPHP 的扩展列表是“白名单制”，不是“黑名单制”。它不会加载你没明确要求的任何扩展，哪怕系统里有。所以构建时多敲一行 docker-php-ext-install 比上线后抓耳挠腮强十倍。
