直接修改Dockerfile构建自定义FrankenPHP镜像:基于dunglas/frankenphp固定版本基础镜像,COPY应用代码至/app,通过ENV DOCUMENT_ROOT=/app/public或ENTRYPOINT指定文档根,确保composer install执行且验证镜像内文件存在,启动时映射-p 8080:8080。

直接修改 Dockerfile 构建自定义 FrankenPHP 镜像
FrankenPHP 官方镜像(docker.io/dunglas/frankenphp)本身是「运行时镜像」,不带构建工具链,也不挂载源码;想把应用代码打进镜像,必须基于它写自己的 Dockerfile,而不是靠 docker run -v 挂载——后者在生产环境不可靠,且无法用于 CI/CD 或容器编排。
关键点:FrankenPHP 的入口是 frankenphp 二进制,它默认从 /app 目录读取 PHP 文件。所以你的代码得复制进去,并确保路径结构匹配路由规则(比如 index.php 在根下,或 public/index.php 配合 DOCUMENT_ROOT)。
- 基础镜像用
FROM dunglas/frankenphp:1.2(推荐固定 tag,避免意外升级破坏兼容性) -
COPY . /app是最简做法,但要注意排除.git、node_modules、vendor(如果本地已装好)等无关目录 - 若项目依赖 Composer,需在 COPY 后加
RUN cd /app && composer install --no-dev --optimize-autoloader,且确保基础镜像里已预装composer(官方镜像已包含) - 不建议在镜像里执行
composer create-project—— 构建层缓存失效快,体积膨胀明显
处理静态资源与 public 目录映射
FrankenPHP 默认以 /app 为文档根,但多数 PHP 项目(Laravel、Symfony)把 Web 入口放在 public/ 子目录。硬把所有文件塞进 /app 会破坏结构,也容易漏掉 .htaccess 或重写规则。
正确做法是把应用整体 COPY 到 /app,再通过环境变量或配置让 FrankenPHP 指向子目录:
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
- 设
ENV DOCUMENT_ROOT=/app/public,FrankenPHP 会自动切换文档根(1.1+ 支持) - 或改用
ENTRYPOINT ["frankenphp", "--document-root=/app/public"](更显式,兼容性略好) - 静态资源(CSS/JS)必须放在
/app/public下,否则 404;/app/assets这类路径不会被自动服务 - 注意
public/.htaccess在 FrankenPHP 中无效——它不走 Apache,要用frankenphp.yaml或路由规则替代重写逻辑
构建与验证镜像是否真包含代码
构建完别急着 docker run,先确认代码确实进了镜像——这是最常被跳过的验证步骤,也是线上 404 的主因。
- 运行
docker build -t myapp .后,执行docker run --rm -it myapp ls -la /app,看输出是否含你的index.php、composer.json等 - 若看到空目录或只有
vendor没有源码,大概率是.dockerignore误删了*或忘了COPY命令 - 启动容器后访问
http://localhost:8080报 500?查日志:docker logs,常见错误如PHP Fatal error: Uncaught Error: Class "App\Kernel" not found,说明autoload没生效,通常是composer install步骤缺失或路径错位 - FrankenPHP 默认监听
:8080,暴露端口记得加-p 8080:8080,别沿用 Nginx 的:80习惯
多阶段构建能减小镜像体积但非必需
如果你的项目要编译前端资源(Vite、Webpack),或需要 npm、phpunit 等开发依赖,才值得上多阶段构建。纯 PHP 应用(无前端构建)直接单阶段更清晰。
- 第一阶段用
node:20-alpine装依赖、构建 JS/CSS,输出到/dist - 第二阶段用
dunglas/frankenphp,只COPY --from=0 /dist /app/public和 PHP 源码 - 注意:FrankenPHP 镜像基于
alpine,若你用了ext-sqlsrv或ext-mongodb这类非 Alpine 官方包,得自己编译扩展或换debian基础镜像——官方frankenphp不提供这些 - 多阶段会让 Dockerfile 变长,CI 缓存链更脆弱;小项目优先保证可读性和可维护性,而非极致体积
真正卡住人的往往不是构建逻辑,而是 DOCUMENT_ROOT 路径和 frankenphp.yaml 的路由匹配没对齐,导致请求根本没进 PHP 而是返回了 404 或静态文件内容。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!










