composer require不接受裸github url，因只识别vendor/name:version格式；须在项目根composer.json的repositories中声明type为vcs的git地址，并确保包名与仓库composer.json中name字段完全一致，且有明确版本标签或dev-分支。
require 时直接写 GitHub 地址为什么报错
不行，composer require 不接受裸 GitHub URL（比如 https://github.com/vendor/repo）。它只认包名 + 版本约束，而包名必须和目标仓库 composer.json 中的 "name" 字段完全一致。常见错误是误以为能写成 composer require github-username/repo-name，结果报 Could not find a matching version of package vendor/name。
真正要做的，是让 Composer “知道”这个 Git 仓库的存在，并告诉它：这个 vendor/name 包，就从这个 Git 地址取。
- 仓库根目录必须有合法的
composer.json，且"name"值如"acme/utils"是你打算在require中使用的完整包名 - 必须打明确的版本标签（如
v1.0.0）或使用dev-开头的分支名（如dev-main），Composer 不会自动猜分支 - 私有仓库不配置认证，
git clone阶段就会卡住——不是 Composer 报错，而是 Git 拒绝连接
repositories 配置必须写在项目根 composer.json 顶层
repositories 是全局开关，不是某个包的配置项。它必须出现在你**正在开发的那个项目的根目录 composer.json 文件最外层**，不能嵌套在 require、config 或子依赖里。
正确写法示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/acme/utils.git"
}
],
"require": {
"acme/utils": "dev-main"
}
}
-
"type": "vcs"是硬性要求，告诉 Composer 这是个 Git/SVN/Hg 仓库，不是 Packagist 上的标准源 -
"url"必须是完整 Git 地址，支持 HTTPS 或 SSH；HTTPS 更易配合 token 认证，SSH 需提前配好密钥 - 如果用了私有仓库但没在
repositories里声明，Composer 根本不会去尝试拉取，也不会提示“找不到源”，只会安静地报版本不匹配
私有仓库必须用 token 或 SSH 认证，不能把 token 写进 composer.json
GitHub/GitLab 私有库需要身份凭证，但绝不能把 token 明文塞进 composer.json（会随代码提交、泄露风险极高）。正确做法是通过 Composer 全局配置注入：
获取 token 后执行：
composer config -g github-oauth.github.com <your-token></your-token>
或对 GitLab：
composer config -g gitlab-oauth.gitlab.com <your-token></your-token>
- GitHub token 需勾选
repo权限；GitLab token 至少要有read_repository - 该配置写入的是
~/.composer/auth.json，属于用户级，不影响其他项目 - 若用 SSH 地址（
git@github.com:acme/utils.git），则确保本地ssh-agent已加载对应私钥，且 GitHub 账户已添加公钥
dev 分支 vs tag 版本：稳定性和可重现性的取舍
用 "acme/utils": "dev-main" 看似方便，但每次 composer update 都可能拉下新提交，导致不同环境行为不一致。生产环境应尽量避免 dev- 分支依赖。
- 打正式 tag（如
v1.2.0）后，"acme/utils": "^1.2"才能锁定语义化版本范围 - GitHub Releases 页面创建 tag 时，务必勾选 “This is a prerelease” 的反选状态，否则 Composer 默认忽略 prerelease 版本
- 若想临时测试某次提交，可用
"acme/utils": "dev-main#abc1234"（abc1234是 commit hash），但仅限调试，不可进composer.lock提交
最容易被忽略的是：即使所有配置都对，只要 composer.json 里的 "name" 和 require 中写的包名有一个字符不一致，整个链路就断在第一步——Composer 根本不会尝试访问那个 Git 仓库。
