答案是源未生效：repositories未置顶、packagist.org未禁用、VCS配置错误或镜像同步延迟；需验证配置位置、禁用官方源、检查URL合法性并手动确认镜像同步状态。
composer require 报 “Package not found” 但包名确认无误
大概率不是包真没了，而是 Composer 根本没去你配的源里找。它严格按 repositories 数组顺序查找，且默认只认 packagist.org 上的 stable 版本。
常见错误现象：
- 运行
composer search vendor/name能搜到，composer require却失败 - 私有包 URL 明明可访问，但报 404 或 “not found”
- 新发布的包在 Packagist 页面已显示，本地却装不上
实操建议：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 执行
composer config --list | grep repositories，确认输出里是否包含你配置的源；若没出现，说明配置未生效（尤其注意项目级composer.json中的repositories会完全屏蔽全局配置） - 检查
repositories是否写在了正确位置：必须是顶层字段，不能嵌套在config或其他对象里 - 私有 VCS 源必须带完整
type和合法url，例如：{"type":"vcs","url":"https://gitlab.example.com/group/lib.git"}；漏掉type或 URL 少个.git后缀，Composer 就会静默跳过 - 确保
packagist.org已显式禁用：在repositories末尾加{"packagist.org": false}，否则即使你写了私有源，它也会 fallback 到官方源并忽略你的配置
用了阿里云/腾讯云镜像还是提示包不存在
镜像不是万能的——它只是缓存，不会“创造”包，更不会同步未发布到 Packagist 的私有包。国内镜像普遍存在 5–30 分钟同步延迟，新版本或刚提交的 tag 往往查不到。
实操建议：
- 手动验证镜像是否已同步：访问
https://mirrors.aliyun.com/composer/p/vendor/name.json（把vendor/name替换为实际值），返回 404 或内容不含目标版本，就是镜像还没同步 - 确认全局镜像配置键名：Composer ≥ 2.2 必须用
repos.packagist（复数），写成repo.packagist会静默失效；运行composer config -g repos.packagist查看输出是否为合法 JSON 对象 - 临时切回官方源验证：运行
composer config -g repos.packagist composer https://packagist.org，再执行composer require vendor/name -vvv；若成功，问题就出在镜像延迟或配置错误 - 清除元数据缓存：仅
composer clear-cache不够，它不强制刷新packages.json；可删掉对应镜像路径缓存：rm -rf ~/.composer/cache/repo/https---mirrors-aliyun-com-composer
私有包 require 失败，但 Git 仓库 URL 可正常 clone
能 clone 不代表 Composer 能识别——它对 VCS 源的解析依赖远程仓库的 composer.json 内容、分支/标签命名、认证方式，三者缺一不可。
实操建议：
- 确保远程仓库根目录存在有效的
composer.json，且其中name字段与你在require中写的完全一致（包括大小写和 vendor 名） - 指定版本时，必须对应真实存在的 Git tag 或分支：要装
"dev-main"，远程就得有main分支；要装"1.2.3"，就得有v1.2.3或1.2.3tag（注意是否带v前缀） - GitHub 私有库需 token 认证：
auth.json必须存在且格式正确，URL 中不能含@username（如https://token@github.com/xxx/yyy.git），否则 Composer 会跳过认证流程 - GitLab / Bitbucket 等平台若启用了自签名证书或反向代理，需额外配置
secure-http: false或信任证书，否则连接会被拒绝，表现也是 “not found”
composer search 能搜到，require 却说版本不匹配或找不到
composer search 只查 Packagist 全局索引，不校验 PHP 版本、扩展、稳定性或你本地的 repositories 配置；而 require 是真安装，会严格按 minimum-stability + repositories + 实际元数据匹配。
实操建议：
- 检查项目
composer.json中的minimum-stability：若设为"stable"，但你要装的是dev-main或beta版，就会直接跳过；可临时加--stability=dev测试：composer require vendor/name --stability=dev - 确认
require命令没误加-w（--with-dependencies）：这个参数会让 Composer 强制合并整个依赖树，一旦已有包锁定了冲突版本，它可能放弃安装并报 “not found”，实际是依赖无法满足 - 运行
composer update --dry-run -v，观察日志中是否出现Reading from cache—— 如果是，说明它根本没联网拉新元数据，得用--refresh强制重载：composer update --refresh vendor/name - 别信
composer.json里空的repositories数组："repositories": []会覆盖全局镜像，导致所有请求都 fallback 到默认源，结果就是私有包永远找不到
最容易被忽略的一点：项目级 composer.json 中任意一个 repositories 配置错误（比如 type 拼错、url 缺协议、JSON 格式损坏），Composer 都不会报错，而是直接跳过整个区块，继续走默认源。所以每次改完配置，务必运行 composer config repo.packagist（不加 -g）确认当前生效的源列表。
