必须显式指定frankenphp镜像版本标签，因官方不维护latest标签，否则会导致构建部署不可预测；需在docker run、dockerfile from及构建参数中严格锁定语义化版本如v1.2.3，并验证frankenphp version与php --version一致性。
docker run 时必须显式指定 tag，不能用 latest
FrankenPHP 官方镜像（dunglas/frankenphp）不维护 latest 标签，每次推送新版本都会覆盖，导致构建或部署行为不可预测。你看到的“能跑”，可能只是碰巧没撞上 breaking change。
必须在 docker run 或 Dockerfile FROM 中写死完整语义化版本，例如：
docker run -v $PWD:/app dunglas/frankenphp:v1.2.3
常见错误现象：
- 今天本地测试正常，明天 CI 构建失败 —— 实际是镜像被更新，新版本改了默认
Caddyfile路径或 PHP 版本 -
docker pull dunglas/frankenphp后发现php --version变成 8.4，而你的扩展只兼容 8.3
验证方式：运行后执行 docker exec -it <container> frankenphp version</container>，输出应与 tag 一致；同时检查 php --version 是否符合预期。
静态构建镜像也需锁定 builder 版本
用 dunglas/frankenphp:static-builder-musl 构建单文件二进制时，builder 镜像本身也有版本演进。不同版本可能默认启用不同 PHP 扩展、调整 opcache 预加载行为，甚至改变 musl 工具链版本。
构建命令中必须明确指定 builder tag：
docker build -t my-app-builder -f Dockerfile.static \ --build-arg BUILDER_IMAGE=dunglas/frankenphp:static-builder-musl-v1.1.0 \ .
关键点：
- builder 镜像 tag 和主镜像 tag 不共享版本号，需单独查 GitHub Releases 确认对应关系
- musl 构建环境对 glibc 主机透明，但 builder 内部的
php-config、pkg-config路径、扩展 ABI 都随版本变化 - 若未锁 builder，某次 CI 重建可能产出无法在目标服务器运行的二进制（
ldd ./frankenphp显示动态链接）
自定义基础镜像时，FROM 行不能省略版本
如果你基于官方镜像做二次封装（比如加 tzdata、预装扩展），Dockerfile 的 FROM 必须带 tag：
FROM dunglas/frankenphp:v1.2.3 AS base
而不是：
FROM dunglas/frankenphp
否则后续所有衍生镜像都继承不确定性。更隐蔽的问题是：某些 CI 平台会缓存 FROM 层，一旦上游镜像更新，你的缓存层可能悄无声息地“变质”。
建议做法：
- 把镜像 tag 写进项目根目录的
.frankenphp-version文件，CI 脚本读取它来构造FROM - 用
docker manifest inspect dunglas/frankenphp:v1.2.3检查该 tag 是否真实存在且含 multi-arch 支持
env 变量注入配置时，版本差异会影响变量解析逻辑
FrankenPHP 的 Caddyfile 支持 {env.MY_VAR} 插值，但不同版本对空值、嵌套插值、默认 fallback 的处理有差异。例如 v1.1.x 会静默忽略未定义 env，v1.2.0+ 则抛出 parse error。
这意味着：即使你固定了镜像版本，若 Caddyfile 中用了未声明的变量（如 {env.FRANKENPHP_CONFIG} 但没传该 env），v1.2.0+ 会启动失败，而旧版可能降级为 localhost。
安全写法：
- 始终用
docker run -e FRANKENPHP_CONFIG=/path/to/caddyfile显式传入关键变量 - 在 Caddyfile 开头加注释标明适配版本：
# Compatible with frankenphp v1.2.3+ - 避免在
php_ini指令里用插值，如php_ini memory_limit {env.MEM_LIMIT}—— 这类写法在 v1.0.x 就不支持
最易被忽略的是：镜像版本锁定后，Caddyfile 语法和 PHP ini 指令的兼容性边界依然存在，必须按实际使用的版本文档校验每一行配置。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
