Composer 2.2+ 必须使用 repositories.packagist.org 替代 repo.packagist，且需重生成 composer.lock、验证镜像支持 2.x 路径、私有源 dist.type 必须为 zip/tar，并注意 Homebrew 2.5.0+ 已移除 self-update。
composer.json 里 repositories 配置键名变了
Composer 2.2+ 开始，官方明确推荐用 repositories.packagist.org 替代旧的 repo.packagist。后者在部分新版中会被静默忽略——你改了镜像地址却没生效，很可能就是这个原因。
常见错误现象：改完 composer.json 还是走默认源、composer install 明明配置了国内镜像却卡在 packagist.org 域名解析。
- 检查当前写法：
"repo.packagist": {"url": "https://packagist.phpcomposer.com", "type": "composer"}→ 这是 1.x 风格，2.2+ 不保证兼容 - 正确写法（2.2+ 推荐）：
"repositories": [{"type": "composer", "url": "https://packagist.phpcomposer.com"}]，或更规范地："repositories.packagist.org": {"url": "https://packagist.phpcomposer.com"} - 注意：
repositories.packagist.org是顶层键，不是嵌套在repositories数组里的；两者不能混用，否则可能被忽略
镜像地址本身要适配 Composer 2.x 下载路径
不是所有镜像都同步支持 Composer 2.x 的二进制分发路径。有些公司内网镜像只代理了 https://getcomposer.org/download/1.x/，而没同步 /2.x/ 目录，导致 php composer.phar self-update --2 失败或下载到旧版。
典型表现：composer --version 显示仍是 1.x，即使命令看起来执行成功。
- 验证镜像是否支持 2.x：
curl -I https://your-mirror.com/download/2.x/composer.phar，看返回状态码是否为 200 - 若不支持，要么升级镜像服务，要么临时绕过镜像直连官方：
php -r"copy('https://getcomposer.org/installer', 'composer-setup.php');"+ 手动校验 SHA384 后安装 - Homebrew 安装的用户注意：从 2.5.0 起，
self-update命令已被移除，必须卸载重装
私有 Packagist 或 Satis 源需确认 API 兼容性
Composer 2.x 对私有仓库返回的 packages.json 格式更严格，尤其关注 dist.type 字段。旧版 Satis 可能仍返回 "type": "pack"，而 2.x 只认 "zip" 或 "tar"。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
错误现象：composer update 报错 Invalid package information 或直接跳过某个私有包，不报错也不安装。
- 检查私有源根目录下的
packages.json，搜索"dist": { "type":，确认值是"zip"或"tar" - Satis 用户需升级到 2.0+ 版本，并在
satis.json中显式设置"archive": {"format": "zip"} - Private Packagist 用户请确认控制台中“API Compatibility”已开启 Composer 2.x 支持（后台设置项）
镜像配置生效后，锁文件必须重生成
镜像只是影响下载来源，但 composer.lock 里记录的是包的原始元数据 URL 和哈希。如果 lock 文件是 1.x 生成的，即使镜像配置正确，2.x 也会因缺少 content-hash 字段拒绝加载，直接退出。
这不是镜像没生效，而是 lock 文件格式不兼容。
- 必须删除
composer.lock和vendor/目录（整个目录，别留子目录） - 运行
composer install，让 2.x 重新解析依赖并生成带content-hash和平台哈希的新 lock 文件 - CI 流水线中务必确保缓存的 lock 文件由 Composer 2.x 生成，否则每次都会失败
镜像配置只是表层，真正卡住升级的往往是锁文件格式、私有源响应结构、以及系统级安装方式带来的权限问题。这些点不手动清理或验证，光改配置没用。
