PHP 缺失或版本过低（需≥7.4，推荐8.1+）及缺少php-zip、php-xml、php-mbstring等扩展是树莓派无法运行Composer的主因；须用curl下载官方PHAR安装，禁用pip或Windows安装器；换源需用repositories.packagist.org键名并清缓存。
确认 PHP 是否可用且版本达标
Composer 是 PHP 工具，不是独立二进制，树莓派上跑不起来的首要原因是 PHP 缺失或太老。Raspberry Pi OS 默认只装 php-cli 的最小集，常漏掉 php-zip、php-xml、php-mbstring 这几个 Composer 必需扩展。
执行 php -v 看版本：低于 7.4 就别折腾了，Composer 2.2+ 已不支持；推荐用 Raspberry Pi OS Bookworm（自带 PHP 8.2）或手动升级到 8.1+。
补全依赖命令：
sudo apt update && sudo apt install php-cli php-zip php-xml php-mbstring php-bcmath php-opcache- 验证扩展是否加载：
php -m | grep -E "zip|xml|mbstring"，缺一个都可能在composer install时卡住或报错 - 别跳过
php-opcache—— 它能显著加速 Composer 的 autoload 生成，尤其在 vendor 包多时
安装 Composer 要绕开 pip 和 Windows 安装器
树莓派是 ARM 架构，但 Composer 本身是 PHP 脚本（composer.phar），不涉及架构编译问题。真正踩坑的是误用错误安装路径或方式：
- ❌ 别用
pip install composer—— 这装的是 Python 版旧版docker-compose，和 PHP 的 Composer 完全无关，纯属混淆 - ❌ 别在树莓派上双击运行 Windows 的
Composer-Setup.exe—— 根本不兼容 - ✅ 正确做法：直接下载官方 PHAR 文件，一行搞定：
sudo curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer - 验证：
composer --version应输出类似Composer version 2.7.7，不是Command 'composer' not found或报 PHP 扩展缺失
换源必须用新版键名 repositories.packagist.org
树莓派上 composer install 卡在 Downloading 不动？90% 是因为用了过时的配置键名，新版 Composer（2.2+）已弃用 repo.packagist，静默忽略导致仍直连 packagist.org。
正确全局换源命令（阿里云镜像）：
composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}'- 注意：URL 结尾必须带
/，否则 Composer 2.5+ 会报Invalid repository type - 验证是否生效：
composer config -g repositories.packagist.org，输出应为完整 JSON 对象，不是空或报错 - 换源后首次运行
composer install前，务必清缓存：composer clear-cache，否则旧元数据还在本地
项目级换源（写入 composer.json）优先级更高，一旦写了 "repositories" 字段，全局配置就失效 —— 协作项目建议用这种方式，Git 提交即同步。
ARM 镜像与 Composer 无关，但容易被一起误判
有人把 docker-compose 在树莓派上启动失败的问题，错误归因到 Composer 换源上。其实完全无关：Composer 只管 PHP 包下载，Docker 镜像拉取慢或失败是另一层问题。
如果你在树莓派上跑 docker-compose up 报错：
-
exec format error→ 是docker-compose二进制没选对架构，和 Composer 无关 -
pull access denied或卡住 → 是 Dockerfile 或compose.yaml里没指定platform: linux/arm64，导致默认拉 x86 镜像 -
permission denied while trying to connect to the Docker daemon socket→ 是用户没加docker组，或 Docker 服务没启，也和 Composer 无关
Composer 和 Docker 是两条线：前者装 PHP 类库，后者运容器。别让 docker 的问题干扰 Composer 的调试路径。
