答案是需满足三个硬条件：仓库根目录有含合法"name"字段的composer.json、存在带dev-前缀的分支或语义化v前缀tag、私有库须预配认证；否则必须通过repositories显式声明vcs源。
直接 composer require 一个 GitHub 仓库，90% 的情况会失败——不是 Composer 不行，而是你没满足它认人的三个硬条件。
为什么 composer require 报 Could not find a matching version of package
Composer 不查 GitHub 页面，也不猜你想要哪个分支。它只做两件事：按包名去匹配 composer.json 中的 "name" 字段，并在你声明的源（Packagist 或自定义 repositories）里找符合版本约束的 commit。
- 仓库根目录必须有合法
composer.json，且"name"字段格式为vendor/name（比如laravel/framework），不能写成github-username/repo-name - 你要引用的分支或 tag 必须存在：分支名要带
dev-前缀（如dev-fix-auth），tag 必须是语义化格式（推荐v1.2.0，不建议1.2.0） - 如果是私有仓库，
git clone阶段就会卡住——你得提前配好 token 或 SSH，而不是等报错再补
绕过 Packagist 直接拉 GitHub 仓库的正确写法
不想公开、还在调试、或刚 push 还没被 Packagist 收录？用 repositories 显式声明 VCS 源，这是最稳的本地开发方式。
batch-git-url-replace
下载
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
-
repositories必须写在项目根目录的composer.json顶层，不是子包或插件配置里 - 类型固定为
"vcs"，URL 填完整 Git 地址："url": "https://github.com/your-org/your-repo.git"或"url": "git@github.com:your-org/your-repo.git" - 别漏逗号——JSON 语法错误会导致整个
composer install失败，尤其在数组末尾加新仓库时 - 多个仓库堆在一起会拖慢
composer update，只留真正需要的
版本约束怎么填：分支、Tag、Commit 的写法差异
指定什么版本，全靠 composer require vendor/name:xxx 后面的字符串，不是改 repositories 里的 URL。
- 引用分支：
dev-main、dev-fix-login（注意dev-是前缀，不是分支名本身） - 引用 Tag：
v2.1.0、1.0.0（无v前缀可能被识别为dev-1.0.0） - 引用某次提交：
dev-main#abc1234（#后是完整 SHA1，不是 short hash） -
dev-main这类开发版默认不随composer update升级，除非显式加--with-dependencies或调低"minimum-stability"
为什么 composer install 拉不到远程最新代码
Composer 默认复用 vendor/ 里已有的 Git 克隆，只检出 composer.lock 记录的 commit，不会自动 git pull。
- 你 push 了新 commit 到
main分支，本地vendor/不会同步更新 - 强制刷新：删掉对应目录
rm -rf vendor/vendor-name，再跑一次composer install - 如果用了
dev-main但想每次拉最新，可加"prefer-source": true到composer.json，但会变慢
最易忽略的点：包名必须和 composer.json 里 "name" 完全一致，大小写、斜杠、连字符都不能错；私有库认证失败时，错误常卡在 git clone 阶段，日志里看不到明显提示，得看详细输出（-vvv）才能定位。
