自定义 repositories 字段会彻底屏蔽全局镜像，哪怕仅为空数组；验证需用 composer config --list | grep repositories.packagist.url，若为空则说明被覆盖；必须检查 composer.json 是否含 repositories 字段，并确保每个源显式声明 "type": "composer" 且 url 以 / 结尾。
自定义 repositories 导致全局镜像失效
只要 composer.json 里存在 repositories 字段（哪怕空数组 "repositories": []），Composer 就会彻底忽略 composer config -g repo.packagist 设置的全局镜像——不是合并，是直接丢弃。这不是 bug，是设计行为。
常见错误现象：
- 明明执行了
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，但composer install日志里仍出现https://packagist.org/packages.json -
composer config --list | grep repositories.packagist.url输出为空
实操建议：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 检查项目级
composer.json是否含repositories字段；如有，确认是否真需要——私有包应优先用"type": "composer"源，而非全量覆盖 - 若必须保留自定义源，务必在每个
repository条目中显式声明"type": "composer"，否则 Composer 会 fallback 到 VCS 模式，跳过镜像代理 - 禁用 packagist.org 时，不要写成
{"packagist.org": false}放在repositories数组开头；正确做法是设"packagist": false在repositories内部，并确保它不是第一条（否则查完私有源就退出）
私有源配置错误让依赖“根本找不到”
自定义源 URL 写错、类型漏填或认证失败，会导致 Composer 静默跳过该源，转而尝试官方源或直接报错“package not found”，但错误信息不提示源本身问题。
常见错误现象：
-
composer require mycorp/private-package报Could not find package mycorp/private-package，但私有仓库页面能正常访问 - 私有包已发布新版本，
composer update却始终拉不到，日志里没请求私有源地址
实操建议：
- 验证源是否被识别：
composer config repositories应输出完整配置，且type字段值为composer - 确保私有源 URL 以
/结尾（如https://packages.mycorp.com/），否则 Composer 会拼出错误路径如.../packages.json→ 404 → 降级 - 若需认证，用
composer config http-basic.packages.mycorp.com username token，别把 token 直接写进 URL（URL 中 token 可能被日志泄露） - 临时测试源可用性：
curl -v https://packages.mycorp.com/packages.json，确认返回 200 + JSON 格式正确
自定义源与缓存冲突导致“有新版却装不上”
换源或更新私有包后，Composer 仍复用旧缓存里的 packages.json，压根不发请求到新源，结果提示 Nothing to install or update，但私有仓库页面已显示 v2.1.0。
原因不是镜像延迟，是本地缓存未刷新，Composer 读的是过期元数据。
实操建议：
- 每次修改
repositories或私有源内容后，必须运行composer clear-cache—— 这是硬性步骤，不可省略 - 若怀疑 provider 分片同步滞后（如 Laravel 11 相关私有组件找不到），加
--refresh：例如composer update --refresh（≥2.5） - 不要信
curl -I看Last-Modified，那只是源站文件时间，不反映 Composer 本地是否已更新缓存 - 验证缓存是否生效：运行
composer install -vvv，末尾应出现类似Reading packages.json from cache at /https---packages-mycorp-com/
conflict/replace 在私有源中引发意外阻断
私有包若在 composer.json 中声明了 conflict 或 replace，这些规则会全局生效——哪怕你没直接 require 它，只要其他已安装包间接拉入，就会触发冲突，且报错位置极隐蔽。
常见错误现象：
- 项目没装
laravel/framework:11，但引入私有包 A 后，composer update直接报don't install laravel/framework 11.0 - 私有包声明
"replace": {"monolog/monolog": "*"}，结果项目里monolog/monolog的功能异常，但composer show显示已安装
实操建议：
-
conflict只用于强互斥场景（如两个包提供同一组 API 且不兼容），别用来“提醒用户注意版本”——那该写文档或require -
replace后必须确保被替代项真能被完全覆盖，否则运行时报错；比如用私有 polyfill 替代ext-mbstring，得确认所有路径都走 polyfill，而不是部分走扩展、部分走 polyfill - 排查时运行
composer prohibits vendor/package:version，它比why-not更直接暴露conflict规则触发点 - 诊断期间可临时注释私有包中的
conflict字段，验证是否为根源；但改完立刻还原，不能留着上线
type 和 URL 结尾斜杠是静默失效的开关，不是“差不多就行”的配置项。漏掉任何一个，Composer 都不会报错，只会默默 fallback，让你花几小时排查网络或锁文件问题。
