首先配置私有仓库源并在composer.json中声明git仓库，推荐使用ssh协议并配置ssh密钥实现安全认证；其次可通过https结合personal access token并利用auth.json存储凭据以提升安全性；然后在require中指定分支如dev-main或打标签使用语义化版本；同时启用vcs缓存提升性能；最后注意排查ssh连接、公钥权限、包名匹配及缓存问题，确保私有依赖稳定加载。
在私有项目中使用 Composer 加载私有 Git 仓库作为依赖，是许多团队开发中的常见需求。尤其当你的组织拥有多个内部组件、SDK 或微服务时，通过 Composer 引入这些私有包可以极大提升开发效率和代码复用性。本文将一步步教你如何配置 Composer 正确加载私有 Git 仓库依赖。
1. 配置私有仓库源（Repository）
Composer 使用 repositories 字段来指定额外的包来源。要在项目中引入私有 Git 仓库，你需要先在 composer.json 中声明该仓库。
支持多种协议，如 SSH、HTTPS 等。推荐使用 SSH，更安全且便于自动化部署。
示例配置：
{
"repositories": [
{
"type": "git",
"url": "git@gitlab.company.com:team/private-package.git"
}
],
"require": {
"company/private-package": "dev-main"
}
}
说明：
- type: 设置为 "git" 表示这是一个 Git 仓库
- url: 使用 SSH 地址（推荐），也可用 HTTPS（需配合 token）
- require: 包名可自定义，但通常与仓库路径对应
2. 认证方式：SSH 密钥配置
使用 SSH 是最方便的方式，无需每次输入密码或 token。
步骤如下：
- 生成 SSH 密钥对（若尚未生成）：
ssh-keygen -t rsa -b 4096 -C "your@email.com" - 将公钥（~/.ssh/id_rsa.pub）添加到 Git 服务器（如 GitLab、GitHub、Gitea）的 Deploy Key 或用户 SSH Keys 中
- 测试连接：
ssh -T git@gitlab.company.com
确保 Composer 能通过系统 SSH 客户端拉取代码。Linux/macOS 默认支持，Windows 推荐使用 WSL 或 Git Bash。
3. 使用 HTTPS + Personal Access Token（备选方案）
如果你必须使用 HTTPS，可以通过 Personal Access Token 实现认证。
- 在 Git 平台（如 GitHub、GitLab）生成一个具有读取权限的 Token
- 在 URL 中嵌入 Token（不推荐明文写在 composer.json）：
{
"repositories": [
{
"type": "git",
"url": "https://oauth2:YOUR-TOKEN@gitlab.company.com/team/private-package.git"
}
]
}
更安全的做法是利用 Composer 的 auth.json 文件隔离敏感信息。
创建 auth.json（位于项目根目录或 COMPOSER_HOME）：
{
"http-basic": {
"gitlab.company.com": {
"username": "oauth2",
"password": "YOUR-TOKEN"
}
}
}
然后 URL 改为普通 HTTPS 地址，Composer 会自动读取认证信息。
4. 指定版本与分支策略
私有仓库通常没有发布正式版本，你可能需要引用特定分支或提交。
常见做法：
- dev-branch-name：引用开发分支，如 "dev-main"
- 打标签后使用稳定版本，如 "1.0.0"
- 临时使用 commit hash（不推荐长期使用）
建议在私有包中也遵循语义化版本，并通过 git tag 发布版本，以便主项目精确控制依赖。
5. 优化性能：启用 VCS 缓存
频繁拉取私有仓库会影响安装速度。Composer 支持缓存 VCS 克隆。
开启方法：
composer config --global cache-vcs-pack true
或在项目中启用：
composer config cache-vcs-pack true
Composer 会将 Git 仓库缓存到本地，加快后续更新速度。
6. 常见问题排查
遇到问题时，可参考以下检查点：
- SSH 是否能正常连接？运行 ssh -T git@... 测试
- 是否把公钥正确添加到 Git 服务器？注意 Deploy Key 需要“只读”权限
- composer.json 中的包名是否匹配？Composer 不会自动推断名称
- 是否清除了 Composer 缓存？使用 composer clear-cache
- 是否设置了正确的 Git 配置？某些环境需设置 git config --global url."ssh://".insteadOf "https://"
基本上就这些。只要配置好仓库源和认证方式，Composer 就能像处理公开包一样管理私有依赖。关键是保持认证安全、结构清晰，避免硬编码凭据。合理使用分支和标签，让私有组件也能享受现代 PHP 包管理的便利。
