FrankenPHP官方镜像（dunglas/frankenphp）基于Alpine、静态链接PHP 8.5并内置Caddy，无需手动编译；精简关键在于禁用冗余扩展、删除无用配置文件、正确处理public目录路径及善用环境变量动态配置。
FrankenPHP 官方镜像（dunglas/frankenphp）本身就是基于 Alpine 构建的，且已静态链接 PHP 8.5、内置 Caddy 和常用扩展，**无需在 Alpine 容器里手动编译安装 FrankenPHP**。所谓“精简版操作”，本质是避免污染镜像、控制体积、适配生产约束——重点不在“装”，而在“怎么用得干净”。
直接用官方镜像，别自己从零构建
很多人想在 Alpine 基础镜像上手动拉源码、装依赖、编译 FrankenPHP，这完全没必要，而且极易翻车：
-
dunglas/frankenphp镜像已是 Alpine + 静态链接 PHP 8.5，体积约 40–50MB（远小于传统 LAMP 的 150MB+） - 它不依赖系统级
php-fpm、nginx或libphp动态库，没有 musl 兼容性风险 - 手动编译会引入
gcc、make、pkgconf等构建工具，哪怕后续apk del，中间层残留仍会让镜像膨胀 20MB+
正确做法：直接 FROM dunglas/frankenphp:latest（或固定小版本如 :v1.2.0），然后只做 COPY 和 ENV 配置。
精简的关键是删掉不需要的扩展和配置文件
官方镜像虽精简，但仍包含部分你项目用不到的扩展（如 pdo_pgsql、ldap、snmp），它们不会自动加载，但会占用磁盘空间和启动扫描时间。清理方法如下：
立即学习“PHP免费学习笔记（深入）”；
- 进入容器执行
php -m查看已启用模块列表 - 禁用不需要的扩展：在
Dockerfile中加一行RUN rm /usr/local/lib/php/extensions/no-debug-non-zts-20250619/extname.so（注意扩展名和实际路径需匹配） - 删除冗余配置：官方镜像自带
/etc/php/conf.d/下多个.ini文件，可RUN rm /etc/php/conf.d/20-*.ini（保留10-opcache.ini和15-frankenphp.ini） - 不要碰
/usr/local/bin/frankenphp或/usr/local/caddy—— 这些是静态二进制，删了就起不来
挂载 vs COPY：静态资源路径必须对齐
FrankenPHP 默认期望 PHP 应用根目录下有 public/ 子目录，且 Caddy 自动把 root 设为 public/。如果你的项目结构不是这样，容易出现 404 或空白页：
- 用
COPY . /app时，确保本地有public/index.php；否则要自定义Caddyfile - 用
volumes挂载时，宿主机路径必须映射到/app，不能是/app/public—— 否则php_server找不到index.php - 若项目无
public/目录（比如旧式index.php在根目录），需覆盖默认 Caddyfile：localhost { root * /app php_server { try_files {path} /index.php } encode zstd br gzip }
环境变量比改 Caddyfile 更安全
官方镜像支持通过环境变量动态注入配置，比直接写死 Caddyfile 更适合 CI/CD 和多环境部署：
-
SERVER_NAME=your-app.example.com→ 自动启用 HTTPS + Let's Encrypt（需开放 80/443 端口） -
FRANKENPHP_CONFIG=worker→ 启用常驻模式（Laravel/Symfony 必开） -
CADDY_GLOBAL_OPTIONS="log {level debug}"→ 调试时打开详细日志 - 不要在 Dockerfile 里
COPY Caddyfile /etc/caddy/Caddyfile—— 官方镜像的 Caddyfile 是模板，会被环境变量覆盖；硬覆盖反而导致SERVER_NAME失效
最易被忽略的一点：FrankenPHP 的 worker 模式依赖 FRANKENPHP_CONFIG=worker 和框架自身的 frankenphp-worker.php 入口文件。Laravel 用户必须确认项目已运行过 php artisan vendor:publish --tag=frankenphp-config，否则即使开了 worker，也还是每次请求重启进程。
