讲师中心 微信公众号

工具推荐

视频效率加速
剧云
剧云

中文短剧剧本制作平台

Laper
Laper

剧本策划到成片协作

AniShort
AniShort

AI短剧协同制作平台

立刻MV
立刻MV

低成本歌曲 MV、视频生成

如何解决 Composer 在 ARM 架构(如 M1/M2 Mac, Raspberry Pi)上的兼容性问题?

胖晨小哥_4586

胖晨小哥_4586

发布时间:2025-12-15 09:08:02

|

456人浏览过

|

来源于php中文网

原创

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

如何解决 composer 在 arm 架构(如 m1/m2 mac, raspberry pi)上的兼容性问题?

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”。解决方法:

Portainer Docker Control
Portainer Docker Control

使用 Portainer API 控制 Docker 容器和堆栈,包括列出容器、启停/重启、查看日志以及从 Git重新部署堆栈。

下载
  • 禁用预编译,强制源码编译: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 可执行文件。

  • 对 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% 的场景。

热门AI工具

更多
咔片AIPPT

一款在线AI演示文稿制作工具,可根据主题和内容需求辅助生成PPT结构与页面,提高演示材料制作效率。

豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

Laper
Laper Hot

Laper是专为编剧、导演和制片人推出的 AI 原生剧本创作工具。

创客贴AI

创客贴AI是一款AI图像与设计工具,AI辅助的智能在线设计工具。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

讯飞智文

一款面向学习和办公场景的AI文档创作工具,可辅助生成PPT与Word文档,提高资料整理和内容制作效率。

花生AI
花生AI Hot

一款AI视频创作工具,主要用于B站推出的AI视频创作工具,适合需要提升相关任务效率的用户。

火山引擎

火山引擎是一款面向企业的云计算与AI服务平台。

WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

相关专题

更多
PHP Symfony框架
PHP Symfony框架

本专题专注于PHP主流框架Symfony的学习与应用,系统讲解路由与控制器、依赖注入、ORM数据操作、模板引擎、表单与验证、安全认证及API开发等核心内容。通过企业管理系统、内容管理平台与电商后台等实战案例,帮助学员全面掌握Symfony在企业级应用开发中的实践技能。

6517

2025.09.11

laravel组件介绍
laravel组件介绍

laravel 提供了丰富的组件,包括身份验证、模板引擎、缓存、命令行工具、数据库交互、对象关系映射器、事件处理、文件操作、电子邮件发送、队列管理和数据验证。想了解更多laravel的相关内容,可以阅读本专题下面的文章。

897

2024.04.09

laravel中间件介绍
laravel中间件介绍

laravel 中间件分为五种类型:全局、路由、组、终止和自定。想了解更多laravel中间件的相关内容,可以阅读本专题下面的文章。

875

2024.04.09

laravel使用的设计模式有哪些
laravel使用的设计模式有哪些

laravel使用的设计模式有:1、单例模式;2、工厂方法模式;3、建造者模式;4、适配器模式;5、装饰器模式;6、策略模式;7、观察者模式。想了解更多laravel的相关内容,可以阅读本专题下面的文章。

2528

2024.04.09

thinkphp和laravel哪个简单
thinkphp和laravel哪个简单

对于初学者来说,laravel 的入门门槛较低,更易上手,原因包括:1. 更简单的安装和配置;2. 丰富的文档和社区支持;3. 简洁易懂的语法和 api;4. 平缓的学习曲线。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。

5081

2024.04.10

laravel入门教程
laravel入门教程

本专题整合了laravel入门教程,想了解更多详细内容,请阅读专题下面的文章。

7510

2025.08.05

laravel实战教程
laravel实战教程

本专题整合了laravel实战教程,阅读专题下面的文章了解更多详细内容。

4916

2025.08.05

laravel面试题
laravel面试题

本专题整合了laravel面试题相关内容,阅读专题下面的文章了解更多详细内容。

9229

2025.08.05

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

100

2026.11.12

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
phpMyAdmin 安装文档
phpMyAdmin 安装文档

共0课时 | 0人学习

phpEnv手册
phpEnv手册

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn