FrankenPHP怎么把静态资源嵌入二进制-php教程-PHP中文网

frankenphp默认不嵌入静态资源，仅打包vendor/下的.php文件；要将public/等静态资源打入二进制，须在caddyfile中配置file_server { embed public/ }，并注意mime类型、路径大小写及框架内硬编码url问题。

frankenphp怎么把静态资源嵌入二进制

FrankenPHP 默认不嵌入静态资源，只 embed PHP 文件

FrankenPHP 的 frankenphp build --embed-vendor 只处理 vendor/ 下的 .php 源码文件，不会打包 public/ 里的 CSS、JS、图片等静态资源。它默认仍通过文件系统读取 public/ 目录——也就是说，你生成的二进制运行时，依然依赖外部 public/ 存在且可读。

想把静态资源打进二进制，必须用 Caddy 的 file_server + embed 模式

FrankenPHP 底层是 Caddy，而 Caddy 支持用 file_server 的 embed 指令将静态文件编译进二进制。但 FrankenPHP 并未暴露该能力给高层命令，需手动干预：

在项目根目录创建 Caddyfile，显式启用 file_server 并指定 embed
embed 路径必须是相对于 Caddyfile 的相对路径（如 embed public/），不能是绝对路径
确保 public/ 下无符号链接或动态生成文件（如 mix-manifest.json 若含 runtime hash，需提前固化）
执行 frankenphp build 时，Caddy 会自动识别并把 embed 声明的目录内容静态编译进二进制

示例 Caddyfile 片段：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

localhost {
    root * public/
    php_server
    file_server {
        embed public/
    }
}

常见错误：嵌入后 404 或 MIME 类型错乱

嵌入静态资源后，常出现请求返回 404 或浏览器提示“Not Found”，或 JS/CSS 加载失败但状态码是 200 —— 这通常是 MIME 类型未正确识别导致：

Caddy 的 file_server 默认根据扩展名推断 MIME 类型，但嵌入模式下若文件无扩展名（如 public/app）、或扩展名不标准（如 .mjs），会 fallback 到 text/plain
解决方法：在 file_server 块中显式添加 mime 指令，例如：mime .mjs application/javascript
另一个坑是路径大小写敏感：Linux 上 public/Css/app.css 和 public/css/app.css 是不同路径，嵌入后无法跨路径匹配
嵌入后 file_server 不再支持 try_files，所以不要在 file_server 块里混用 try_files，应由 php_server 处理路由回退

真正“零目录依赖”的二进制，还得清理 public/ 外部引用

即使静态资源已嵌入，Laravel 等框架仍可能在运行时硬编码引用 public/ 下的路径（比如生成 asset URL 时拼接 https://example.com/js/app.js）。这类行为不被嵌入影响，但会导致部署后 URL 错误：

检查 APP_URL 和 MIX_ASSET_URL 是否设为相对路径或空值，避免生成绝对域名
Laravel 中慎用 asset() 在服务端渲染时输出完整 URL；改用 mix() 或前端构建时注入 CDN 域名
确认所有 <link> / <script></script> 标签路径不带 public/ 前缀——因为嵌入后，Caddy 已把 public/ 当作 Web 根，路径直接从 / 开始即可