Composer在Apple Silicon上默认按ARM64环境安装依赖，导致vendor含架构敏感二进制；解决方法是禁用平台检测、跳过原生插件、构建时在目标平台单独安装扩展，并复用Composer下载缓存而非vendor目录。
为什么 composer install 在 Apple Silicon 上默认不生成 x86_64 兼容的 vendor 目录？
因为 Composer 本身不感知目标 CPU 架构，它只按当前运行环境（ARM64）下载和安装扩展、二进制依赖（如 phpunit、larastan、symfony/flex 的 bin 脚本），而这些工具的预编译二进制（尤其是 PHP 扩展的 .so 文件或 Go 编写的 CLI 工具）通常绑定宿主机架构。Docker 构建时若用 --platform linux/amd64，但 vendor/ 里混着 ARM64 的二进制或扩展，运行就会报错：exec format error 或 cannot open shared object file。
如何让 composer install 输出真正跨平台可用的 vendor？
核心思路：不让 Composer 下载任何平台敏感的二进制或扩展，把“平台相关”部分完全交给 Docker 构建阶段处理。关键操作是禁用本地平台推断，并强制跳过所有需要编译/下载原生二进制的插件：
- 加
--ignore-platform-reqs防止因 PHP 版本、扩展缺失被阻断（但慎用，仅用于构建缓存） - 设环境变量
COMPOSER_IGNORE_PLATFORM_REQS=1+PHP_VERSION=8.2（与目标镜像一致）避免插件误判 - 禁用会拉取平台专属二进制的插件：在
composer.json中显式关闭symfony/flex的自动安装逻辑，或删掉hirak/prestissimo（已废弃）、phpstan/extension-installer等可能触发下载的包 - 确保
composer.lock中所有包都未标记platform依赖（检查是否有"ext-igbinary": "*"这类条目；如有，删掉并composer update --lock）
Docker 构建时怎么复用 ARM64 主机上的 vendor 缓存？
不能直接挂载 vendor/ 进 x86_64 容器（架构不兼容），但可以缓存 composer install 的下载层 —— 即 ~/.composer/cache。做法是：在构建命令中用 --cache-from 和 --cache-to 配合 BuildKit，同时将宿主的 Composer 缓存目录通过 BUILDKIT_PROGRESS=plain + DOCKER_BUILDKIT=1 挂载为 build secret 或临时 volume（实际更稳的是用 docker buildx bake + registry cache）：
- 先在 ARM64 Mac 上跑一次：
composer install --no-scripts --no-autoloader --prefer-dist（生成干净的vendor/autoload.php结构，不含二进制） - Dockerfile 中用
COPY composer.json composer.lock ./→RUN --mount=type=cache,target=/root/.composer/cache composer install --no-scripts --no-autoloader --prefer-dist - 最终镜像里再单独
RUN docker-php-ext-install或pecl install所需扩展（此时在目标平台执行，安全）
容易忽略的坑：autoload 生成和平台无关性验证
composer dump-autoload 默认生成的 vendor/autoload.php 是架构中立的，但如果你用了 classmap 或 files 加载方式，且其中包含条件判断（比如 if (PHP_OS_FAMILY === 'Darwin')），就可能埋雷。验证方法很简单：
- 在 x86_64 容器里运行：
php -d extension=phar.so -r "include 'vendor/autoload.php'; echo 'OK\n';" - 检查
vendor/composer/autoload_classmap.php是否含绝对路径（如/Users/xxx/...）—— 若有，说明composer install在生成 classmap 时读了本地路径，必须加--no-scripts和--no-plugins彻底隔离 - 不要信任
composer show --platform的输出，它反映的是当前环境，不是 lock 文件承诺的目标平台
最麻烦的地方往往不在 Composer 本身，而在于某个 dev 依赖悄悄拉了 macOS-only 的二进制，或者 post-install-cmd 脚本里硬编码了 uname -m 判断。遇到 exec format error 时，先 ls -l vendor/bin/ 看文件头：file vendor/bin/phpunit —— 如果显示 ARM64，那就得回源头砍掉这个依赖。
