必须严格配置镜像源并清理缓存才能生效：全局配置需用非root用户执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/并验证输出为完整json；项目级配置须在composer.json中添加repositories对象并禁用packagist.org；最后必须删除vendor/和composer.lock后运行composer install。
要让 Composer 从国内或私有镜像源拉取依赖，必须准确写入仓库配置，否则即使命令执行无报错，Composer 仍会静默回退到 packagist.org；漏掉键名单复数、type 值、URL 末尾斜杠中任意一项，都会导致配置无效。
全局配置阿里云镜像（适合本地开发）
执行一条命令即可生效，但必须严格满足三个硬性条件：
第一步：打开终端，确保当前用户是日常开发所用账户（不是 root），然后运行：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
第二步：验证是否真正写入——运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，例如：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
【空、null、Key not found 或仅返回 https://packagist.org，说明配置失败】
第三步：若返回为空，大概率是用了 sudo 执行命令，导致配置写入了 root 用户的 ~/.composer/config.json；此时需先确认当前用户身份（whoami），再检查 ~/.composer 目录归属：
ls -ld ~/.composer
如归属非当前用户，运行 chown -R $USER ~/.composer 后重试第一步。
项目级配置（CI/宝塔/Docker 必选）
全局配置在 GitHub Actions、宝塔后台、Docker 容器中基本无效，因为这些环境以 www、runner 等非登录用户运行，读不到你的用户目录配置。项目级配置随代码交付，优先级更高，且不依赖执行用户。
方法一：命令行安全追加（推荐）
进入含 composer.json 的项目根目录 → 运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
注意：不加 -g，且确保当前目录下存在 composer.json。
方法二：手动编辑 composer.json（更可控）
打开 composer.json，在根节点（与 require 同级）添加：
"repositories": { "packagist.org": false, "packagist": { "type": "composer", "url": "https://mirrors.aliyun.com/composer/" } }
【"packagist.org": false 必须显式声明，否则 Composer 仍会 fallback 到官方源】
方法三：处理已有 repositories 数组的兼容写法
若原 composer.json 中 "repositories": [] 是数组格式，直接运行 config 命令会失败；需先手动改为 "repositories": {}（空对象），保存后再执行方法一的命令。
换源后必须执行的清理动作
配置写对只是第一步，旧缓存和锁文件会强制沿用原始源地址，导致换源完全无效。
删掉 vendor/ 目录和 composer.lock 文件，这两项缺一不可。
然后运行 composer install（不是 update）——只有 install 会重新解析依赖并生成新 lock 文件，其中所有包地址才会真正指向镜像源。
这一步操作起来很简单，直接把 vendor/ 和 composer.lock 拖进回收站就行，但跳过它，前面所有配置都白做。
