如何解决 Composer 在 ARM 架构（如 M1/M2 Mac, Raspberry Pi）上的兼容性问题？

Composer 本身支持 ARM，问题多出在 PHP 运行环境、扩展、Docker 镜像及 vendor 二进制上；需确认 php -v 显示 arm64/aarch64，用 Homebrew 安装原生 PHP，禁用预编译扩展，指定 --platform linux/arm64 拉取镜像，并清理 x86_64 二进制。

Composer 本身是 PHP 编写的命令行工具，不依赖 CPU 架构，所以它在 ARM 设备（如 Apple M1/M2 Mac、Raspberry Pi）上可以正常运行——真正出问题的通常是它安装或更新的 PHP 扩展、二进制依赖（如 xdebug、swoole、protobuf 的预编译扩展），以及部分包里硬编码的 x86_64 构建脚本。

确认 PHP 运行环境是否原生支持 ARM

很多 ARM 用户的问题根源其实是用了 Rosetta（x86_64 兼容层）运行的 PHP，导致扩展加载失败或性能下降。请先检查：

• 运行 php -v，看输出中是否含 arm64（M1/M2）或 aarch64（Raspberry Pi）；若显示 x86_64，说明 PHP 是通过 Rosetta 或 Intel 版本安装的
• 用 which php 确认路径：Homebrew 安装的原生 arm64 PHP 通常在 /opt/homebrew/bin/php；MacPorts 或手动编译的也可能有对应路径
• 推荐使用 Homebrew 安装原生 PHP：arch -arm64 brew install php（M1/M2），或 Raspberry Pi 上用 sudo apt install php-cli php-zip php-xml php-mbstring（确保启用 arm64 源）

安装扩展时避免 x86_64 预编译包

像 xdebug、swoole、grpc 这类扩展默认会尝试下载预编译的 .so 文件，但官方包往往只提供 x86_64 版本，导致报错 “cannot open shared object file” 或 “mach-o, but wrong architecture”。解决方法：

• 禁用预编译，强制源码编译：pecl install -f xdebug（加 -f 跳过架构检查），或设置环境变量：export PEAR_INSTALL_DIR=$(php -r "echo dirname((new ReflectionExtension('zip'))->getFileName());") 后再安装
• 对 Composer 包中带 bin 的工具（如 pestphp/pest，laravel/pint），优先用 composer global require 安装，而非下载二进制；必要时可改用纯 PHP 实现版本（例如用 phpunit/phpunit 替代某些含原生二进制的测试工具）
• 检查 composer.json 中是否引用了仅限 x86 的私有包或脚本（比如用 bin/xxx 调用 shell 工具），替换成跨平台等价命令（如用 php -S 替代某 x86-only dev server）

处理 vendor/bin 下脚本的架构兼容问题

有些包（如 laravel/sail、symfony/cli）会在 vendor/bin 放 shell 脚本或二进制，而这些脚本可能调用 x86_64 Docker 镜像、或内嵌非 ARM 可执行文件。

标签： composer arm架构 php linux laravel js git json docker github 编