Composer 2.2+ 镜像配置失效主因是键名从repo.packagist升级为repositories.packagist.org，旧键名被静默忽略；必须配合"type":"composer"、URL末尾斜杠及-g参数，并清除缓存、删除vendor和composer.lock后重装。
Composer 2.2+ 镜像配置键名失效：repo.packagist 被静默忽略
Composer 升级到 2.2+ 后，repo.packagist 这种写法不再被识别——你改了镜像地址却还在走 packagist.org，不是网络慢，是配置根本没加载。官方已明确废弃该键名。
- 旧写法（1.x 兼容但 2.2+ 不保证生效）：
"repo.packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 新写法（必须用其一）：
"repositories.packagist.org": {"url": "https://mirrors.aliyun.com/composer/"}（顶层键，不能嵌套） - 或数组形式：
"repositories": [{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}] - 验证是否生效：
composer config -g --list | grep repositories，确认输出中含repositories.packagist.org或repositories数组项
composer.lock 仍含 1.x 元数据导致解析失败
升级后 composer install 直接崩溃或卡死，大概率是 composer.lock 里残留了旧版字段（如 content-hash 结构差异、插件元数据），2.x 解析器拒绝处理。
- 不要手动编辑
composer.lock——它由 Composer 自动生成，人工修改极易出错 - 安全做法：
rm -f composer.lock && composer install（前提是composer.json正确且有镜像源） - 若项目依赖私有包，先确保私有源的
packages.json中dist.type是"zip"或"tar"，否则 2.x 会报Invalid package information - 执行前清缓存：
composer clear-cache，避免旧缓存干扰
项目级 repositories 字段让全局配置彻底失效
你在终端用 composer config -g repo.packagist ... 看似成功，但进项目一跑 install 还是走原站——因为只要 composer.json 里有 "repositories": [...]（哪怕空数组），全局配置就完全被跳过，不是优先级低，是直接不读。
- 检查项目根目录
composer.json是否含repositories字段；若有，删掉或改为空对象"repositories": {} - 推荐做法：在项目目录下运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加-g），它会自动写入composer.json的repositories数组，key 固定为"packagist" - 注意：如果原
composer.json是"repositories": []，需先手动改为"repositories": {}再执行，否则报错
vendor 目录归属错误引发连锁写入失败
Permission denied 报错路径常指向 vendor/ 或 composer.lock，但真实原因是目录所有者被污染——比如之前用 sudo composer install 创建了 vendor/，现在普通用户无法覆盖 root 创建的文件。
- 别急着
chmod 777或sudo chown -R——这可能破坏软链接或触发 IDE 文件监听冲突 - 正确做法：
rm -rf vendor composer.lock，再用当前用户运行composer install - 若报错路径是
~/.composer/cache/或~/.composer/vendor/，同样检查归属：ls -ld ~/.composer，必要时chown -R $USER:$USER ~/.composer - Windows WSL 用户特别注意：
/mnt/c/下运行composer install易因跨系统权限模型冲突失败，应把项目移到~/projects/等原生路径
实际修复时，最容易被忽略的是：**composer.lock 和 composer.json 的结构一致性必须与当前 Composer 版本严格匹配**。换源、清缓存、改权限这些操作都只是表象，核心在于确认配置键名、锁文件格式、目录归属三者是否同时适配 2.2+ 的解析规则。
