Composer require GitHub项目失败的根本原因是其不解析URL而严格依赖仓库composer.json中"name"字段与命令中包名逐字符一致，且该文件必须存在。
能直接用 composer require 引入 GitHub 项目，但必须满足硬性条件，否则会报 Could not find a matching version of package vendor/name —— 不是命令写错，而是 Composer 根本没“认出”那个仓库是个合法包。
为什么 composer require 直接加 GitHub 地址会失败？
Composer 不解析 GitHub URL 路径来推断包名。它只认两件事：包名（vendor/name）和版本约束，且这个包名必须和目标仓库根目录下 composer.json 文件里的 "name" 字段**逐字符一致**。
- ❌ 错误写法：
composer require myuser/myrepo（假设 GitHub 地址是https://github.com/myuser/myrepo），但仓库composer.json里写的是"name": "acme/utils" - ✅ 正确前提：先确认对方仓库的
composer.json存在且"name"值明确，比如"name": "spatie/laravel-ray" - ⚠️ 没
composer.json？composer require会立刻终止，不尝试 clone 或 fallback
怎么指定分支、Tag 或某次提交？
靠版本约束字符串控制，不是改 URL 或加参数。Composer 会先查你配的源（或 Packagist），再按这个约束去匹配 commit。
- 引用公开分支：
composer require spatie/laravel-ray:dev-main（对应main分支） - 引用带
v的 Tag：composer require spatie/laravel-ray:v1.32.0 - 引用某次提交：
composer require spatie/laravel-ray:dev-main#abc1234（注意#后是完整 SHA1，不是短哈希） - ⚠️
dev-开头的版本默认 stability 是dev，若项目"minimum-stability"是stable，需显式加--stability=dev或在composer.json中临时调低
私有 GitHub 仓库怎么 require？
不能只靠 composer require 命令完成。必须提前配置认证，否则 git clone 阶段就卡住，报 Failed to clone https://github.com/xxx/yyy.git 或权限拒绝。
|Git删除了文件，但还会在Git 仓库历史中遗留。 - 想要从 Git 历史移除敏感信息（密码、密钥、token、私钥） - 想要删除意外提交的大文件 - 想要重写 Git 历史、移除特定文件的所有痕迹 - 提到 "force push"、"重写 commit 历史" - 需要从所有分支、所有 tag 中删除某个文件
- GitHub 推荐用 Personal Access Token：Settings → Developer settings → Tokens → Generate new token，勾选
repo - 把 token 存进 Composer 全局凭据：
composer config -g github-oauth.github.com - 别把 token 写进
composer.json！也别用 HTTPS URL + 用户名密码（GitHub 已弃用密码认证） - 如果坚持用 SSH，确保本地
ssh-agent已加载密钥，且 GitHub 账户已添加对应公钥
repositories 配置不是必须的，但某些场景绕不开
绝大多数公开包走 Packagist 就够了；只有当你 require 的包**不在 Packagist 上**（比如内部工具库、未提交到 Packagist 的实验项目），才需要手动加 repositories。
- 必须写在项目根
composer.json的顶层"repositories"数组里，不是子依赖里 - 类型固定为
"vcs"，URL 填完整 Git 地址："url": "https://github.com/your-org/internal-tool.git" - 加完记得检查 JSON 逗号——末尾多一个、少一个都会导致
composer install报JSON decode error - 多个私有源堆在一起会显著拖慢
composer update，建议只加当前真要用的
最常被忽略的一点：Composer 对 Git 仓库的识别完全依赖 composer.json 的存在和正确性，而不是 GitHub 页面是否可访问、Star 数多少、或者 README 写得多漂亮。先 git clone 下来看一眼根目录有没有这个文件，比反复试 require 命令高效得多。
