Composer需在composer.json中配置"repositories"块并设"type": "vcs"才能识别私有Git仓库；必须用SSH URL或带Token的HTTPS URL认证；require中须用"dev-main"等明确版本约束；Token应通过环境变量注入而非硬编码。
如何让Composer识别私有Git仓库
Composer默认只信任packagist.org上的公开包，要拉取私有Git仓库，必须在composer.json中显式声明仓库源。GitLab和GitHub的私有仓库不能靠“自动发现”加载，必须手动添加"repositories"配置块，并指定"type": "vcs"。
常见错误是直接写"https://gitlab.example.com/group/repo.git"却不加"type"字段，导致Composer完全忽略该仓库；或者把私有仓库地址误放在"require"里，结果报错"Could not find package xxx"。
- GitLab/GitHub私有仓库必须用SSH URL（如
git@gitlab.example.com:group/repo.git）或带Personal Access Token的HTTPS URL（如https://<font color="red">TOKEN</font>@gitlab.example.com/group/repo.git） - SSH方式需提前配置好本地
~/.ssh/config并确保ssh -T git@gitlab.example.com能通 - HTTPS方式的Token必须有
read_package_registry（GitLab）或repo（GitHub）权限
如何在require中正确引用私有仓库的分支或标签
私有仓库不发布到Packagist，所以"require"里不能只写包名，必须配合版本约束明确指向具体分支、标签或提交哈希。Composer不会自动解析dev-main为最新提交，它需要你显式声明。
例如，想使用GitLab上my-org/my-package的main分支最新代码，composer.json应这样写：
{
"repositories": [
{
"type": "vcs",
"url": "https://<font color="red">glpat-xxxxxx</font>@gitlab.example.com/my-org/my-package.git"
}
],
"require": {
"my-org/my-package": "dev-main"
}
}
-
"dev-main"表示跟踪main分支的HEAD，每次composer update都会拉取最新提交 - 用
"1.0.x-dev"可锁定某分支的语义化前缀（需仓库有对应分支名） - 用
"dev-main#abc1234"可强制固定到某次提交，避免意外更新 - 如果仓库没有设置
"name"字段（即composer.json里没写"name": "my-org/my-package"），Composer会拒绝安装
为什么composer install失败并提示“Could not fetch”
这个错误几乎总是认证问题：Composer尝试克隆仓库时被Git服务器拒绝。不是网络不通，而是凭据无效或缺失。
- 检查是否用了HTTPS URL但没在URL里嵌入Token（
https://token@...），或Token已过期/权限不足 - 检查是否用了SSH URL但
ssh-agent没加载密钥，或~/.ssh/known_hosts里缺少目标主机指纹（首次连接时需交互确认） - GitLab自托管实例要注意：如果启用了
require_two_factor_authentication，个人Token必须由启用2FA的账号生成 - 运行
composer config -g github-oauth.github.com <font color="red">xxx</font>对GitHub有效，但对GitLab无效——GitLab必须走URL内嵌Token或SSH
如何避免把Token硬编码进composer.json
把Token写死在composer.json里会随代码提交到仓库，极不安全。正确做法是利用Composer的环境变量替换机制。
将HTTPS URL改为占位符形式，再通过环境变量注入实际值：
{
"repositories": [
{
"type": "vcs",
"url": "https://${GITLAB_TOKEN}@gitlab.example.com/my-org/my-package.git"
}
]
}
- 在部署机或CI环境中设置
export GITLAB_TOKEN="glpat-xxxxxx" - 确保
composer install执行时该环境变量已生效（CI中常需在job script开头显式export） - 注意：Windows PowerShell中环境变量语法不同（
$env:GITLAB_TOKEN="..."），且Composer在Windows下对变量扩展支持较弱，优先用WSL或Docker
Git凭证助手（git config --global credential.helper store）对Composer无效，它只影响手动git clone，不参与Composer内部调用。
