直接结论：用 repositories + type: "vcs" 声明 git 仓库地址，配合 ssh 或 https 凭据缓存，就能让 composer 正常拉取私有包——不需要自建 packagist，也不必改全局配置。
直接结论：用 repositories + type: "vcs" 声明 Git 仓库地址，配合 SSH 或 HTTPS 凭据缓存，就能让 Composer 正常拉取私有包 —— 不需要自建 Packagist，也不必改全局配置。
为什么 composer.json 里加 "type": "vcs" 就能识别私有 Git 仓库？
Composer 默认只认 packagist.org 上的包。加了 "type": "vcs" 后，它会把指定 URL 当作一个「可扫描的 Git 源」，自动解析该仓库的 composer.json 文件、读取 name 和所有 Git tag（如 v1.0.0），然后纳入版本候选列表。
常见错误现象：
- 执行
composer require acme/utils报错Could not find package acme/utils—— 很可能漏了repositories配置，或name字段写成了utils而不是acme/utils - 拉到的总是
dev-main分支，不是你打的v2.1.0tag —— 检查 Git 仓库是否已git push --tags，且 tag 名符合语义化版本（不能是2.1.0或release-2.1）
HTTPS 方式访问 GitLab/Gitee 私有库，怎么避免输密码？
不能把账号密码硬编码进 composer.json，也不能每次 composer install 都手动输。正确做法是让 Git 自动注入凭证：
Convert Github Repository
下载
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
- 在 GitLab/Gitee 后台生成一个最小权限的个人访问令牌（PAT），只勾选
read_repository - 运行这条命令（替换
<token></token>和域名）：git config --global url."https://oauth2:<token>@gitlab.example.com/".insteadOf "https://gitlab.example.com/"</token> - 验证是否生效：
git ls-remote https://gitlab.example.com/acme/utils.git—— 应该直接返回 refs，不报 401
注意：如果公司 Git 服务启用了双因素认证（2FA），SSH 是更稳的选择；HTTPS + PAT 在某些内网代理环境下可能被拦截，此时需额外配置 http.sslVerify = false（仅限可信内网）。
SSH 方式配置后仍提示 Permission denied (publickey)？
这个错误几乎都卡在密钥没被 Git 正确使用上，和 Composer 本身无关：
- 确认本地已生成密钥：
ssh-keygen -t ed25519 -C "your@email.com"，且公钥已添加到 GitLab/Gitee 账户的 SSH Keys 设置页 - 检查
composer.json中的url是否为 SSH 格式："git@gitlab.example.com:acme/utils.git"（不是 HTTPS！） - 运行
ssh -T git@gitlab.example.com测试连通性；如果失败，可能是 ssh-agent 没启动或没加载密钥：eval "$(ssh-agent -s)"+ssh-add ~/.ssh/id_ed25519 - Git 默认走系统 SSH，但某些 Windows 环境下 Git Bash 会忽略
~/.ssh/config，建议显式配置 Host 别名并绑定 IdentityFile
私有包升级后业务项目不更新？
Composer 缓存的是包的元数据（比如有哪些 tag），不是代码本身。升级失败往往是因为：
- 没运行
composer update acme/utils，只跑了composer install—— 后者只按composer.lock安装，不会拉新版本 - 私有仓库打了新 tag，但本地没
git fetch --tags，导致 Composer 扫描不到新版本（尤其在 CI 环境中，git clone默认不 fetch tags） -
composer.json里写的版本约束太死，比如"acme/utils": "1.0.0"，必须改成"^1.0"或"dev-main"才能匹配后续 patch 版本
最易被忽略的一点：私有包的 composer.json 如果修改了 autoload 规则（比如从 psr-4 改成 classmap），必须运行 composer dump-autoload，否则类自动加载会失效 —— 这个动作不会被 install 或 update 自动触发。
