90%的Composer仓库配置错误源于repositories中某条配置不合法：URL协议被拒、type与url不匹配或服务端未返回预期JSON；须逐条验证type/url合规性，并用curl或git ls-remote测试真实可达性。
Composer仓库配置错误导致require失败、包找不到或invalid repository报错，90%不是网络问题，而是repositories数组中某条配置本身不合法——URL协议被拒、type与url不匹配、服务端未返回预期JSON结构，必须逐条验证真实可达性。
检查repositories中每条配置的type和url是否匹配
Composer对不同type有硬性校验规则，不满足就直接判“无效”，连HTTP请求都不会发。
type: "vcs"必须配可git clone的地址，例如"https://gitlab.example.com/group/pkg.git"；写成网页地址"https://gitlab.example.com/group/pkg"就会静默跳过该仓库。
type: "composer"要求URL可访问且返回合法packages.json，比如"https://packages.example.com/"（注意末尾必须有/）；少个/或路径错一层（如/api/packages.json）都会404后静默回退官方源。
type: "package"不需要url字段，但必须提供完整package对象，含name、version、dist或source字段，缺一不可。
运行composer diagnose，它会明确指出哪一条repository“failed to parse”，比盲猜快得多。
验证私有仓库URL是否真能返回有效响应
别信Composer报错里的模糊提示，直接用底层命令测试真实可达性。
对type: "composer"仓库：执行curl -I https://your-repo.com/packages.json，看是否返回HTTP/2 200，且响应体是合法JSON（含顶层packages键）。
对type: "vcs"仓库：执行git ls-remote -h https://your-git.com/user/repo.git，能列出ref才算通；若报fatal: unable to access，就是证书、代理或DNS问题。
【注意】Composer默认不走系统.gitconfig的proxy设置；公司有代理时，得单独设COMPOSER_HTTP_PROXY环境变量。
Docker场景下，localhost指的是容器自身——想连宿主机服务，URL得写成http://host.docker.internal:8080（Linux需加--add-host=host.docker.internal:host-gateway启动）。
排查Packagist镜像全局配置失效原因
composer config -g repo.packagist总没反应，不是命令没跑，是三个地方一错就静默失效。
第一步：键名必须是repo.packagist（不能多写一个s），写成repos.packagist字段虽存进去但不认。
第二步：type值必须显式写composer，只写URL不带type，新版Composer直接fallback官方源。
第三步：URL必须以/结尾，例如https://mirrors.aliyun.com/composer/，缺末尾/会导致请求拼成/composerpackages.json而404。
验证是否成功：运行composer config -g repo.packagist，输出应为完整JSON，形如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。
项目级repositories配置被覆盖的典型场景
全局配置在CI、宝塔、Docker等多用户场景下极易失效——~/.composer路径可能根本不存在，或者写到了runner用户家目录里，而实际执行的是www用户。
项目级配置才是稳定解法：在项目根目录composer.json的repositories数组里显式声明所有源，包括兜底的Packagist条目。
私有vcs仓库必须放在数组最前面，再补上带"packagist": false的Packagist条目，确保路由可控。
【关键前提】项目级repositories数组会默认关闭隐式packagist.org源，必须显式添加{"type":"composer","url":"https://packagist.org","packagist":false}兜底。
Path仓库报“Source path does not exist”的快速定位
出现该错误说明Composer无法找到你指定的本地目录，通常是因为路径配置错误或环境差异导致。
确认路径是否正确：在终端执行ls ../my-package（Linux/macOS）或dir ..\my-package（Windows），检查目标目录是否存在。
路径必须指向含composer.json的目录，不能指向其父级或空目录；末尾不可加/，"url": "../my-package/"会导致静默忽略整个仓库。
避免使用绝对路径，除非必要且跨环境一致；推荐用通配符如"../packages/*"指向多个包目录，但依然要求该目录存在且子目录结构合法。
Windows用户需以管理员身份运行终端，否则符号链接创建失败且无提示；Docker需加--cap-add=SYS_ADMIN并确保挂载方式支持symlink。
