Composer全局镜像不区分PHP架构，多平台共用同一配置会导致二进制扩展兼容性问题；根本原因在于镜像仅加速下载，不校验目标架构（如aarch64/x86_64）的扩展兼容性，需结合platform约束、显式PHP路径及项目级repositories配置共同解决。
composer config -g repo.packagist 为什么在多架构 PHP 下失效
全局镜像只改下载地址，不绑定 PHP 架构（x86_64 / aarch64 / x86）或版本。当你在 Apple Silicon（aarch64）和 Intel（x86_64）机器上共用同一份 ~/.composer/config.json，或在 Docker 多平台构建中复用缓存时，Composer 仍会用当前运行的 PHP 解释器去解析依赖——而该解释器可能不支持目标架构编译的扩展（如 grpc、protobuf），导致 composer install 成功但 vendor/autoload.php 运行时报 undefined symbol 或 failed to load extension。
常见错误现象：
PHP Warning: PHP Startup: Unable to load dynamic library 'grpc.so'-
composer install没报错，但php artisan serve直接崩溃 - Docker 构建成功，但容器启动失败：提示
cannot open shared object file: No such file or directory
根本原因不是镜像本身，而是镜像拉下来的包未按当前架构校验二进制兼容性。Packagist 镜像源不区分架构，它只提供统一 URL，最终装什么包，由 Composer 的 platform 和实际 PHP 运行时共同决定。
项目级 repositories 必须带 {"packagist.org": false} 且放首位
只有项目级配置能随代码提交、被 CI/CD 显式感知，并与目标架构强绑定。但写法容错率极低，错一个字符就退化为走官方源。
立即学习“PHP免费学习笔记（深入）”；
正确写法（注意结构、逗号、末尾斜杠）：
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{"packagist.org": false}
]
}
必须满足以下全部条件：
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
-
"repositories"是数组，不是对象 - 镜像对象必须是第一个元素
-
{"packagist.org": false}是独立数组项，不能合并进前一项 -
url值末尾必须有/（https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌） - 删掉
vendor/和composer.lock后再执行composer install；update不重读repositories
显式指定 PHP 路径 + platform 配置才是双保险
镜像解决下载慢，platform 解决包选型，显式调用 PHP 解决运行时匹配——三者缺一不可。
例如你在 Apple Silicon 上部署需适配 aarch64 的 Laravel 11 项目：
- 先确认你用的是原生 arm64 PHP：
/opt/homebrew/bin/php@8.2 --version输出含arm64 - 在
composer.json中写死平台约束："config": {"platform": {"php": "8.2.27"}}（补丁号不能省） - 安装时强制用目标 PHP：
/opt/homebrew/bin/php@8.2 ./composer.phar install - CI/CD 中避免 PATH 干扰：不用
composer install，始终用完整路径调用
注意：--platform=php:8.2.27 是临时覆盖，比修改 composer.json 更适合流水线动态切换；但别和 --ignore-platform-req=php 混用，后者会绕过所有 PHP 版本检查，埋下 runtime 兼容隐患。
Docker 多架构构建中镜像配置容易漏的点
Docker 构建阶段（composer:alpine）和运行阶段（php:8.2-apache）是两个隔离环境。你在构建阶段配的全局镜像，对运行阶段的 PHP 容器完全无效。
安全做法分两步：
- 构建阶段（
composer容器）：确保RUN composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/执行成功，且composer install用的是该镜像 - 运行阶段（
php容器）：要么在Dockerfile中重复配置：RUN composer config -g repo.packagist https://mirrors.aliyun.com/composer/，要么直接把composer.json里的repositories配置写全，靠项目级优先级兜底 - 验证是否生效：进入容器后运行
composer config --list | grep repo，确认输出包含你配的 URL
最容易被忽略的是：即使镜像配置正确，若基础镜像里 PHP 缺少 curl 或 openssl 扩展，Composer 仍会静默 fallback 到官方源并超时——所以务必检查 php -m | grep -E "(curl|openssl)"。
