如何解决 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 可执行文件。

Blackink AI纹身生成

创建类似纹身的设计，生成独特纹身

80

查看详情

• 对 Docker 相关工具（如 Sail）：确保本地 Docker Desktop 已启用 “Use the new Virtualization framework”（M1/M2 必须开启），并拉取 --platform linux/arm64 镜像，例如：docker run --platform linux/arm64 -it php:8.3-cli
• 遇到 Permission denied 或 bad CPU type in executable 错误时，进 vendor/bin 查看对应文件类型：file xxx；若是 Mach-O x86_64，就删掉重装，或手动替换为 GitHub Release 页面提供的 arm64 版本（如有）
• 临时绕过：用 php vendor/autoload.php 加载逻辑，或直接调用 PHP 类（如 php -r "require 'vendor/autoload.php'; (new \Some\Cli())->run();"）

其他实用技巧

不是所有问题都来自底层架构，一些配置和习惯也能大幅减少兼容性摩擦：

• 升级到最新稳定版 Composer：curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer（确保下载的是支持 arm64 的 phar）
• 禁用某些不必要插件：某些 Composer 插件（如 hirak/prestissimo）已废弃且无 ARM 支持，可在 composer.json 的 config.plugins 中显式关闭
• 使用 composer config -g platform.arch arm64 告知 Composer 当前平台架构（部分包会据此选择不同 dist 包）

基本上就这些。ARM 兼容性问题多数不是 Composer 本身的问题，而是生态链中某个环节卡在 x86 假设上。理清 PHP 运行时、扩展构建方式、Docker 平台、以及 vendor 二进制来源这四层，就能覆盖 95% 的场景。

以上就是如何解决 Composer 在 ARM 架构（如 M1/M2 Mac, Raspberry Pi）上的兼容性问题？的详细内容，更多请关注php中文网其它相关文章！