必须在项目根目录composer.json的repositories数组中显式声明"type": "vcs"，url不带.git后缀且需通过600权限auth.json配置认证；包名与git tag（如v1.0.0）须严格匹配，否则报“could not find package”。
直接用 vcs 类型声明即可，不是 git、package 或其他类型；不配就根本找不到包，报错永远是 Could not find package，而不是认证失败或网络超时。
composer.json 里必须写 "type": "vcs"
Composer 对 Git 仓库的识别只认 "type": "vcs"，写成 "git" 或 "github" 都会被忽略。这个字段必须出现在项目根目录 composer.json 的 repositories 数组里，且 url 值要满足：
- HTTPS 地址不带
.git后缀（如"https://gitlab.example.com/group/pkg"），否则部分版本会 fallback 失败 - SSH 地址格式为
"git@gitlab.example.com:group/pkg.git"，注意末尾.git是允许的（但非必需） - URL 必须能在命令行用
git clone直接拉下，否则 Composer 一定失败 -
repositories必须是 JSON 数组，不能是对象；已有该字段就追加，别覆盖
auth.json 是唯一合法的凭据载体
HTTPS 方式访问私有 Git 仓库（GitLab/GitHub）必须靠 auth.json，拼 token 到 URL（如 https://token@...）虽偶能工作，但不被推荐，且在 CI 中极易暴露凭证。
- 文件必须放在项目根目录（与
composer.json同级）或$COMPOSER_HOME下 - Linux/macOS 必须执行
chmod 600 auth.json，否则 Composer 静默忽略 - GitLab 用户名固定填
"oauth2"，密码填glpat-xxx（不是账号密码） - GitHub 填
"github-oauth": {"github.com": "ghp_xxx"}，PAT 权限需含repo - SSH 方式不依赖
auth.json，但要求ssh-agent已加载对应私钥
require 的包名和版本必须严格匹配 Git 状态
Composer 不读私有包自身 composer.json 里的 version 字段，它只看 Git 的 tag 和分支名。写错就装不上，且错误提示毫无指向性。
- 包名（如
"myorg/utils"）必须和私有仓库内composer.json的name字段**逐字一致**，大小写敏感 - 要支持
"^1.0"，必须打语义化 tag：v1.0.0或1.0.0（v1.0不识别） - 用
dev-main需在项目根composer.json加"minimum-stability": "dev"和"prefer-stable": false - 运行
composer show myorg/utils --all可确认 Composer 实际识别出哪些版本，比猜靠谱得多
composer require 不会自动补 repositories
这是最常踩的坑：执行 composer require myorg/utils 只会在 require 段加一行，repositories 完全不动。新机器或 CI 上首次安装必然失败。
- 必须手动编辑
composer.json，先补好repositories，再运行require - CI 环境中，别依赖
composer config --global写凭据——不同项目可能需要不同 token - 本地开发若用
path类型临时调试，记得上线前切回vcs，否则部署会崩 - 清除缓存不是万能的：
composer clear-cache之后仍需composer install或require才触发重解析
真正卡住的地方往往不是语法，而是 Git tag 格式不对、auth.json 权限没设对、或者 repositories 被误删——这些都不会报明确错误，只会安静地跳过你的私有源。
