EMBED 参数仅打包指定路径下可被 PHP 正常加载的非忽略文件，不包含 .git、node_modules、composer.lock 等；require/include 路径必须相对于 EMBED 根目录，越界即不可见，.env 等需显式传入路径才能生效。
EMBED 参数实际打包的文件范围
EMBED 参数不是“把整个项目目录无差别塞进去”，而是以指定路径为根，递归打包该路径下所有非 Git 忽略、非构建中间产物、且能被 PHP 正常加载的文件。它不打包 .git、vendor/bin/、node_modules/（除非你显式 COPY 进去）、composer.lock（仅当被 PHP 代码 require 时才可能间接包含），也不打包 .env 文件本身——但如果你在代码里用 file_get_contents('.env')，而该文件又在 EMBED 路径内，那它就会被打包。
常见误判点：
-
EMBED=dist/app/只打包dist/app/下的文件，不会自动带上上层的composer.json或public/ -
vendor/是否被打包，取决于你是否在EMBED路径中包含了它；FrankenPHP 官方推荐做法是先composer install --no-dev --optimize-autoloader，再把vendor/和应用代码一起放进EMBED目录 -
public/目录里的静态资源（如index.php、robots.txt）必须显式放在EMBED路径下，否则启动后 404
哪些文件会被 PHP 运行时真正读取并生效
FrankenPHP 启动时只加载 EMBED 路径下的 index.php（或 Caddyfile 指定的入口），其余文件是否被读取，完全取决于运行时逻辑：
-
require/include的路径必须相对于EMBED根目录，不能用绝对路径或../跳出范围 -
autoload.php必须存在且可被找到，否则类自动加载失败；建议把vendor/autoload.php放进EMBED并确保其<strong>DIR</strong>能正确解析依赖路径 -
.env类配置文件：如果用vlucas/phpdotenv，它默认从当前工作目录找.env；但 FrankenPHP 的工作目录是二进制所在路径，不是EMBED路径——所以得显式传入路径：Dotenv::createImmutable(<strong>DIR</strong>.'/../app/')
容易被忽略的隐式依赖项
这些文件不显眼，但缺了就报错，且不会被 EMBED 自动识别：
立即学习“PHP免费学习笔记（深入）”；
-
php.ini或ini配置片段：FrankenPHP 不打包系统级php.ini，所有 PHP 配置需通过frankenphp_set_ini()或 Caddyfile 的php_ini指令设置 - 扩展的 .so 文件：
ext-opcache.so等已编译进 FrankenPHP 二进制，无需打包；但自定义扩展（如ext-myext.so）必须提前编译进镜像，不能靠EMBED加载 -
public/.htaccess：完全无效，FrankenPHP 不解析 Apache 规则；等效逻辑要写进 Caddyfile 的handle块 -
storage/和bootstrap/cache/：Laravel 这类框架需要可写目录，但它们不能打在EMBED里（会只读），必须由运行时挂载或初始化
打包后最常遇到的“文件找不到”错误，90% 是因为：
-
require 'config/database.php'中的路径没对齐EMBED根 -
vendor/autoload.php里写的<strong>DIR</strong>.'/../src'在嵌入后指向了错误位置 -
file_exists('migrations/')返回 false，因该目录不在EMBED内，而代码又没做 fallback 处理
EMBED 本质是“把一份可执行的 PHP 应用快照固化进二进制”，不是魔法压缩包。它的边界非常硬：路径即信任边界，越界即不可见。
