必须使用dunglas/frankenphp:static-builder-musl镜像并显式指定--platform linux/arm64，构建时需clean EMBED路径、用docker-php-ext-install显式安装扩展，验证须满足file显示aarch64+statically linked且ldd返回not a dynamic executable。
必须用 static-builder-musl 镜像，且显式指定平台
FrankenPHP 的 ARM64 静态二进制不能在 x86_64 主机上“直接编译出来”，哪怕你本地是 Apple Silicon（M1/M2/M3）也不行——musl 工具链和目标平台 ABI 必须严格匹配。唯一可靠路径是使用官方提供的多平台构建镜像：dunglas/frankenphp:static-builder-musl，并强制指定构建平台为 linux/arm64。
常见错误现象包括：
-
file ./frankenphp显示 “ELF 64-bit LSB pie executable, x86-64” —— 说明镜像没选对或平台未锁定 - 构建产物在 ARM64 服务器上执行报
cannot execute binary file: Exec format error—— 实际是 x86_64 二进制被误传
实操建议：
- 拉取镜像时加
--platform linux/arm64：docker pull --platform linux/arm64 dunglas/frankenphp:static-builder-musl - Dockerfile 中必须写明
FROM --platform=linux/arm64 dunglas/frankenphp:static-builder-musl - 构建命令里不要依赖宿主机
uname -m，所有平台判断由镜像内./build-static.sh根据EMBED和环境变量推导
EMBED 路径要干净，且不能漏掉 vendor/
ARM64 构建过程本身不比 x86_64 复杂，但更容易因目录污染导致构建失败或运行时报 Class not found。因为静态构建会把 EMBED=dist/app/ 下的所有内容（含 PHP 代码、autoload、扩展）打包进二进制，路径错一层或少一个目录，启动就直接退出。
立即学习“PHP免费学习笔记（深入）”；
典型误操作：
- 把整个 Git 仓库（含
.git/、node_modules/、tests/）一起 COPY 进镜像 → 二进制体积暴涨，且可能触发 musl 链接器符号冲突 -
COPY . .后没清理，vendor/里混着 x86_64 编译的扩展（如某些 PECL 扩展预编译包）→ 构建阶段不报错，运行时报undefined symbol
正确做法：
- 先在干净目录中准备应用：
composer install --no-dev --optimize-autoloader --ignore-platform-reqs - 确认
vendor/autoload.php可被正常 require，再 COPY 到/go/src/app/dist/app/ - 检查
EMBED值是否以/结尾（如dist/app/），否则路径拼接会出错
PHP 扩展必须用 docker-php-ext-install 显式安装
musl 环境下没有 php.ini 动态加载机制，所有扩展必须在构建阶段编译进二进制。ARM64 镜像里的 docker-php-ext-install 已适配 aarch64，但参数稍有不同。
关键点：
-
pdo_mysql和pdo_sqlite二选一，同时装会导致undefined reference to sqlite3_*—— musl 的符号解析比 glibc 更严格 -
mbstring、curl、json是内置的，不用重复装；但ctype、iconv、openssl需显式声明 - 扩展顺序有影响：比如
pdo必须在pdo_mysql之前安装，否则后者找不到 PDO API
推荐安装命令（写在 Dockerfile 的 RUN 行中）：
RUN EMBED=dist/app/ \
PHP_EXTENSIONS="ctype,iconv,openssl,pdo,pdo_sqlite" \
./build-static.sh
验证产出是否真为 ARM64 静态二进制
构建完成后别急着上传，必须在本地用标准工具链验证。很多团队跳过这步，结果部署到生产 ARM64 服务器后卡在启动第一秒，日志全空。
验证三步法：
- 查架构：
file ./frankenphp-linux-arm64输出应含ARM aarch64和statically linked - 查依赖：
ldd ./frankenphp-linux-arm64必须返回not a dynamic executable（不是动态可执行文件） - 查运行：
qemu-aarch64-static ./frankenphp-linux-arm64 --version可在 x86_64 宿主机上做基础兼容性测试（需安装qemu-user-static）
容易被忽略的是：即使 file 显示 aarch64，如果构建时用了 glibc 镜像或漏了 --platform，ldd 仍可能显示 libc.so.6 => /lib64/libc.so.6 —— 这种二进制在纯 musl 的 Alpine ARM64 上根本跑不起来。
