Composer require 不能直接拉取任意私有 Git 仓库，必须同时满足四个硬性条件：包名与仓库 composer.json 中 name 字段完全一致；repositories 显式声明于项目根 composer.json 顶层且 type 为 "vcs"；HTTPS 方式需正确配置 auth.json 或 token，SSH 方式需密钥可用；require 时必须指定合法版本约束（如 dev-main 或 v1.2.0）。
composer require 不能直接拉取任意私有 Git 仓库——它必须满足包名、源声明、认证、版本标识四个硬性条件，缺一不可。
repositories 必须显式写在项目 composer.json 顶层
Composer 不会自动探测或 fallback 到你“以为它该知道”的私有地址。哪怕你已配置阿里云镜像、甚至全局auth.json，只要没在当前项目的 composer.json 里声明 repositories 数组，composer require 就会安静地报错：Could not find a matching version of package vendor/name。
-
repositories必须是 JSON 数组（不是对象），且位于项目根目录的composer.json顶层 - 每项必须含
"type": "vcs"和完整可git clone的url（如"<a href="https://www.php.cn/link/e31f9ee04a301ce1b709777c8a9aa7f1">https://www.php.cn/link/e31f9ee04a301ce1b709777c8a9aa7f1</a>"或"git@github.com:myorg/my-package.git"） - 多个私有源时，把最常用的放数组首位；若同时用国内镜像，需加
"packagist.org": false禁用兜底，否则 Composer 会在私有源未命中后仍去查官方源 - 删掉
composer.lock、清缓存（composer clear-cache）、再运行composer install或composer require
包名必须和仓库 composer.json 的 name 字段完全一致
composer require 后面写的包名（如 myorg/my-package）不是 GitHub 路径，也不是仓库 URL 片段，而是目标仓库根目录下 composer.json 文件中 "name" 字段的值，一字不差。
- 错误示例：
composer require myorg/my-package，但仓库composer.json里写的是"name": "myorg/my_package"（下划线 vs 连字符） - 错误示例：
composer require github-username/repo-name，但实际name是"acme/utils" - 私有仓库若没
composer.json，或name字段为空/非法，composer require直接失败，不提示具体原因，只报“找不到包”
HTTPS 私有仓库必须配 token 或 auth.json，不能裸 URL
用 HTTPS 地址（如https://www.php.cn/link/e31f9ee04a301ce1b709777c8a9aa7f1）时，git clone 阶段就会因无认证被拒绝。Composer 不会弹出密码框，也不会读取 git config credential.helper，它只认两种方式：
-
在全局或项目级
auth.json中配置：{ "http-basic": { "gitlab.example.com": { "username": "oauth2", "password": "your-personal-access-token" } } }注意：auth.json权限必须为600，否则 Composer 忽略 或者把 token 嵌进 URL（仅限 GitLab/GitHub）：
<a href="https://www.php.cn/link/0e80618b36a7cff483be988ad75140d5">https://www.php.cn/link/0e80618b36a7cff483be988ad75140d5</a>
但这种方式极不推荐：token 可能被日志、Git 历史、CI 缓存泄露，且composer update时可能重写 URL 导致 token 暴露
SSH 方式更安全：用 git@ URL，并确保宿主机已配好 SSH key（ssh -T git@gitlab.example.com 能通）
require 后必须指定合法版本约束，不能只写包名
Composer 不会默认拉main 或 master 分支。你必须显式告诉它要哪个版本，靠 require 行末的版本字符串控制：
- 引用分支：
composer require myorg/my-package:dev-main（注意dev-前缀） - 引用 tag：
composer require myorg/my-package:v1.2.0 - 引用 commit hash（不推荐长期使用）：
composer require myorg/my-package:dev-main#abc1234
关键点：
- 分支名必须真实存在，且该分支的
composer.json中name字段匹配 - 如果仓库只有
main分支但没打任何 tag，dev-main是唯一可用的稳定引用方式 -
^1.0这类约束只在有符合语义化版本的 tag（如v1.0.0,v1.2.3）时才生效；否则 Composer 找不到满足条件的版本
真正容易卡住的地方，往往不是语法错误，而是：仓库 composer.json 的 name 和你 require 的名字对不上、repositories 写在了子包里而不是项目根、或者 HTTPS 认证凭据根本没生效——这些都不会报明确错误，只会静默失败。
