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://TOKEN@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://glpat-xxxxxx@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 xxx对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内部调用。