能解决，但仅限 composer ≥ 2.5；它强制丢弃本地 packages.json 和 provider-*.json 缓存（15 分钟内不过期），从当前配置的中文镜像源重拉最新元数据，不删 zip 包；执行前须确认镜像地址正确且未被项目级 repositories 配置覆盖。
composer update --refresh 能否解决中文镜像元数据不同步
能，但仅限 Composer ≥ 2.5。它专为元数据缓存问题设计，不删 ZIP 包，只丢弃 packages.json 和 provider-*.json，强制从当前配置的镜像源重拉最新索引。
常见错误现象：你在 packagist.org 上看到 monolog/monolog 已发布 v3.6.0，但运行 composer update monolog/monolog 却返回 “Nothing to install or update”。
原因不是镜像没更新，而是 Composer 默认读取 ~/.composer/cache/repo/https---mirrors.aliyun.com-composer/packages.json（15 分钟内不过期），跳过网络请求。
- 执行前务必确认镜像地址正确：
composer config -g repo.packagist应输出类似https://mirrors.aliyun.com/composer/ - 若用的是老版本 Composer（≤ 2.4），
--refresh参数不存在，只能手动删缓存目录：rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer -
composer clear-cache不解决问题——它清的是 dist 包和部分 JSON，但packages.json缓存仍被复用
如何验证中文镜像是否真同步了你要的包
别信网页界面或 composer diag ——它默认只测 packagist.org，完全不检查你配的镜像。
真正有效的验证方式是直接查镜像的元数据接口：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 先获取当前生效镜像：
composer config -g repos.packagist.url（注意是复数repos，单数repo在 Composer 2.2+ 中已失效） - 查全量索引是否更新：
curl -I https://mirrors.aliyun.com/composer/packages.json，必须返回HTTP/2 200 - 查具体包是否存在：
curl -s https://mirrors.aliyun.com/composer/p2/vendor/package-name.json | jq -r '.packages."vendor/package-name" | keys[]' | sort | tail -3 - 对比官方源输出：
curl -s https://packagist.org/p2/vendor/package-name.json | jq -r '.packages."vendor/package-name" | keys[]' | sort | tail -3，版本不一致即为同步延迟
项目级 repositories 配置会静默屏蔽全局镜像
这是最常被忽略的失效原因。你在终端执行了 composer config -g repos.packagist.url https://mirrors.aliyun.com/composer/，但进项目一跑 composer require，日志里却出现 Downloading https://packagist.org/...。
本质是项目根目录的 composer.json 里写了 "repositories" 字段，它会完全覆盖全局设置，哪怕值为空数组也会触发 fallback 行为。
- 检查是否被覆盖：
composer config --list | grep repositories.packagist.url，如果无输出，说明项目配置优先级更高 - 查看项目配置：
grep -A5 '"repositories"' composer.json，常见陷阱包括残留的"url": "https://packagist.phpcomposer.com"（该源已停用） - 临时修复：删掉
composer.json中的"repositories"段，或将其改为有效镜像："url": "https://mirrors.aliyun.com/composer/" - CI/CD 环境尤其要注意：GitHub Actions 默认无全局配置，必须显式加
--repository=https://mirrors.aliyun.com/composer/
插件市场（如 Composer 插件、metapackage）同步更慢的特殊处理
Composer 插件（type: composer-plugin）和 metapackage（type: metapackage）在部分中文镜像中同步频率更低，甚至被漏同步——因为它们依赖的 provider 文件（如 provider-2024-07.json）体积大、解析逻辑复杂。
现象：执行 composer require phpunit/phpunit 报 No matching package found，但该包在 Packagist 上存在且非私有。
- 手动查 provider 文件：
curl -s https://mirrors.aliyun.com/composer/provider-2024-07.json | grep -i 'phpunit/phpunit' - 若无结果，说明 provider 尚未同步，此时
--refresh也无效，需等下一轮轮询（阿里云通常 5–15 分钟） - 紧急绕过：临时切回官方源：
composer config -g repos.packagist.url https://packagist.org，装完再切回来 - 长期建议：对关键插件类依赖，在
composer.json中显式指定"minimum-stability": "stable"，避免因 dev 分支未同步导致解析失败
repos.packagist.url 的拼写（复数 repos）和项目级 repositories 字段的存在——这两点导致绝大多数“镜像配置了却没生效”的问题。
