Composer安装私有Git仓库包需在composer.json顶层repositories中声明"type": "vcs"及可clone的URL，require包名须与私有库composer.json中name字段完全一致，认证通过auth.json（HTTPS）或SSH密钥（SSH）配置，版本依赖Git tag或分支名。
Composer 本身不发布包，只消费包；所谓“发布到私有仓库”，实际是让私有 Git 仓库（GitLab/GitHub）能被 composer require 正确识别和安装。漏掉源注册、认证、版本标识任一环节，都会报 Could not find package。
repositories 配置必须写对 type 和 url
私有包不会自动出现在 Packagist 上，必须在业务项目的 composer.json 顶层显式声明源。常见错误是把 URL 写成网页地址、漏写 "type": "vcs"，或误用 "package" 类型。
-
"type"必须是"vcs"，不是"git"、"package"或留空；写错就静默忽略 -
"url"必须是可git clone的地址：SSH 格式如git@gitlab.example.com:acme/utils.git，HTTPS 格式如https://gitlab.example.com/acme/utils.git - 不建议带
.git后缀的 HTTPS 地址在部分旧版 Composer 中 fallback 成功，但官方明确要求省略；GitLab/GitHub 官方文档和最新实践都推荐保留.git后缀以确保克隆可靠 - 不能写成网页链接（如
https://gitlab.example.com/acme/utils），否则报No valid composer.json was found
auth.json 位置、权限和结构三者缺一不可
HTTPS 方式拉取私有 Git 仓库时，90% 的失败源于 auth.json 配置失效——它不报错，只是跳过读取。
- 必须放在 Composer 全局配置目录：
~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows）；项目根目录下的./auth.json无效 - 文件权限必须是
600（Linux/macOS）：运行chmod 600 ~/.composer/auth.json，否则 Composer 直接忽略 - 内容必须是合法 JSON，外层为对象：
{"http-basic": {"gitlab.example.com": {"username": "gitlab-ci-token", "password": "glpat-xxx"}}} -
http-basic和github-oauth是并列字段，不能嵌套；GitHub 推荐用github-oauth字段，GitLab 必须用http-basic - 域名填
gitlab.example.com，不是完整 URL；Token 需含read_repository（GitLab）或repo（GitHub）权限
版本约束必须匹配 Git 分支或 tag，不是 composer.json 里的 version
Composer 对 VCS 仓库完全忽略私有库 composer.json 中的 "version" 字段，只认 Git 的分支名（如 dev-main）和语义化 tag（如 v1.0.0）。
- 没打任何 tag 的仓库，唯一可用版本是
dev-main（或dev-master），但需确保项目composer.json中设"minimum-stability": "dev"，否则默认跳过 - 想用
"^1.0"这类约束，必须打带v前缀的 tag：v1.0.0、v2.1.3；v1.0或1.0.0不被识别 - 分支别名（如
"dev-main": "1.0.x-dev"）要写在私有包自己的composer.json里，不是业务项目中 - CI 环境中若用
COMPOSER_AUTH注入凭证，注意该变量仅对http-basic有效，github-oauth不支持
私有包自己的 composer.json 必须含合法 name 字段
即使仓库地址、认证、版本全对，composer require acme/utils 仍失败？大概率是私有仓库根目录的 composer.json 没写 "name"，或格式不合规。
-
"name"必须是vendor/name格式，全小写，不含空格或大写字母，例如"acme/utils"、"myorg/logging" - 必须与
require中写的完全一致，大小写敏感；"ACME/utils"或"acme/Utils"都无法匹配 -
"autoload"字段建议配置（如 PSR-4），否则类无法自动加载，但不是安装失败的直接原因 - 不要在私有包
composer.json中写"version"字段来“指定版本”——它会被忽略，纯属误导
最易被忽略的是：Git 仓库 URL 是否真能被 git clone 执行成功。在 CI 或容器环境里，别只信本地测试结果；先手动跑一遍 git clone https://gitlab.example.com/acme/utils.git，再查 auth.json 权限和结构，最后看 composer.lock 里是否真写入了该包的 source 信息——缓存可能让你误判配置已生效。
