需在 composer.json 的 repositories 中声明 vcs 类型仓库并确保 Git 项目 composer.json 的 name 与 require 的包名完全一致，同时配置 auth.json 认证和正确版本约束（如 dev-main）。
怎么在 composer.json 里加 Git 仓库作为包源
Composer 默认只认 Packagist，要拉私有 Git 项目，得手动告诉它“这个地址对应哪个包名”。关键不是加仓库，而是让 Composer 能把 Git 地址和 vendor/ 里的命名对上号。
常见错误是直接写 "repositories": [{"type": "vcs", "url": "https://git.example.com/my/package"}] 就以为完事了——其实这只是注册源，还没声明依赖。
- 必须在
repositories里声明类型为vcs，URL 是 Git 仓库地址（支持 HTTPS、SSH） -
name字段不能随便写：Git 仓库根目录下必须有composer.json，且里面的"name"（如"myorg/my-package"）要和你require的完全一致 - 如果仓库没托管在 GitHub/GitLab 等主流平台，建议加
"no-api": true避免 Composer 尝试调用不存在的 API - SSH 地址（如
git@git.example.com:my/package.git）需要本地已配置好 SSH key，否则composer install会卡住或报Permission denied (publickey)
为什么 composer require 找不到私有包
最常踩的坑是：仓库注册了，require 也写了，但执行时报 Could not find package xxx at any version。这通常不是网络问题，而是包名或版本不匹配。
Composer 查找包时，先查 repositories 列表，再按 name 匹配，最后看有没有满足版本约束的 version 或分支别名（如 dev-main）。
- 确认私有仓库的
composer.json中"name"和require的字符串一模一样（包括大小写、斜杠方向） - 如果想用
main分支，require写"myorg/my-package": "dev-main"；别写"dev-master"，除非分支真叫master - 如果仓库没打 tag，又没设
"minimum-stability": "dev"，Composer 默认不装dev-前缀的版本 - 运行
composer clear-cache再试一次——缓存可能记住了旧的失败结果
composer update 不同步最新提交？
私有 Git 包默认按 dist（压缩包）安装，不是每次都 git clone。所以即使远程仓库 push 了新 commit，本地 vendor/ 也不会自动更新，除非你强制刷新或改用 source 模式。
- 临时同步最新：加
--prefer-source参数，比如composer update myorg/my-package --prefer-source，这样会走git clone+git checkout - 永久生效：在
composer.json根级加"config": {"preferred-install": {"myorg/my-package": "source"}} - 注意性能：频繁用
--prefer-source会变慢，尤其大仓库；CI 环境建议用dist+ 打 tag 控制发布节奏 - 如果用了
--prefer-dist却发现没更新，可能是 Composer 缓存了旧的 zip URL，删掉vendor/myorg/my-package再composer install
私有 Git 仓库认证失败的几种典型报错
权限问题在私有场景里太常见，错误信息看着像网络问题，实际全是认证链断了。
-
Failed to download myorg/my-package: The "https://git.example.com/my/package/zipball/..." file could not be downloaded (HTTP/1.1 401 Unauthorized)→ HTTP 认证缺失，需在auth.json配置 token 或账号密码 -
Cloning into '/path/to/vendor/myorg/my-package'... Permission denied (publickey)→ SSH key 没加载或权限不对，检查ssh -T git@git.example.com是否通 -
Could not fetch https://git.example.com/my/package, enter your password to access this repository→ Composer 尝试交互式输入密码，但 CI 或无终端环境会卡死，必须提前配好auth.json -
auth.json必须放在用户 home 目录（~/.composer/auth.json）或项目根目录，内容格式严格：{"http-basic": {"git.example.com": {"username": "...", "password": "..."}}}
Git 仓库地址、包名、认证方式、版本写法，四个点只要一个没对齐，就会静默失败或报错偏移。调试时别猜，先 composer config --list | grep repo 看源是否真加载了，再 composer show myorg/my-package -v 看它到底想从哪拉、为什么拉不到。
