设置私有仓库 Composer怎么配置Git地址【进阶】

私有仓库必须用 composer.json 的 repositories 字段声明

Composer 不会自动发现或加载你本地或 Git 上的私有包，必须显式告诉它“去哪找”。不配 repositories，composer require 会直接报 Could not find package xxx 或 Package not found。

常见错误是只改了 auth.json 却忘了加 repositories，结果认证通过了，但 Composer 根本没去那个地址查包。

• type 必须是 vcs（Git、SVN、HG 都算），不能写成 git 或 github
• url 要指向 Git 仓库根目录（即包含 composer.json 的那个仓库），不是某个分支或 tag 页面
• 如果用 SSH 地址（如 git@github.com:org/private-repo.git），确保本地 ssh-agent 已加载对应密钥
• HTTPS 地址若需认证，靠 auth.json 补充凭证，不是拼在 URL 里（https://token:x-oauth-basic@github.com/... 已被弃用且不安全）

 auth.json 放哪？权限和路径优先级要搞清

Composer 查 auth.json 有固定顺序：当前项目根目录 → COMPOSER_HOME 环境变量指定目录 → 默认全局路径（如 ~/.composer/auth.json）。项目级 auth.json 最安全，避免凭据泄露到全局。

最容易踩的坑是权限设错：auth.json 文件权限不能是 644 或更宽松，否则 Composer 会拒绝读取并静默跳过——连警告都不给。必须是 600（仅属主可读写）。

• 项目级路径：./auth.json（与 composer.json 同级）
• 内容结构必须是标准 JSON，外层是对象，http-basic 和 github-oauth 是两个独立字段，别混在一起
• GitLab 私有实例要用 http-basic，填域名（如 "gitlab.example.com"），不是完整 URL
• GitHub 私有仓库推荐用 github-oauth + Personal Access Token（scope 至少含 read:packages 和 delete:packages）

Git 仓库的 composer.json 里 version 字段不能乱写

私有包能被正常 require，前提是 Composer 能解析出稳定版本。如果你用 dev-main 或 dev-master 当作版本号，那没问题；但一旦写了 "version": "1.0.0"，就必须打对应 Git tag，否则 Composer 安装时会报 Could not find package xxx at version 1.0.0。

原因：Composer 对 vcs 类型仓库，默认只识别 tag 和 branch 名作为版本，不解析 composer.json 里的 version 字段——除非你手动加 "dist" 配置（极少用，且易出错）。

• 推荐做法：不写 version 字段，靠 Git tag 管理版本（git tag v1.0.0）
• 开发阶段用 dev- 前缀分支名（如 dev-feature/login），require 时写 "vendor/package": "dev-feature/login"
• 如果非要写 version，必须同时配 "dist"，且 "dist.url" 指向 zip 包地址，"dist.reference" 对应 commit hash —— 这绕过了 Git 自动发现，维护成本高

运行 composer update 前先确认是否启用了 --with-dependencies

私有包常依赖其他私有包，而 Composer 默认只更新直接依赖。如果没加 --with-dependencies（或缩写 -W），子依赖里的私有仓库配置可能被忽略，导致安装失败或拉到旧版公共包。

另一个隐形问题是缓存：Composer 会缓存 vcs 仓库的元数据（比如 tag 列表），但不会自动刷新。新 push 了 tag，不清理缓存就 update，很可能装不到最新版。

• 首次引入私有包或新增了 tag 后，建议执行：composer clear-cache && composer update --with-dependencies
• CI 环境中，务必确保 auth.json 已正确挂载且权限为 600，否则整个流程会在某一步静默失败
• 用 composer show -p 可查看当前已加载的私有仓库列表，验证 repositories 是否生效

事情说清了就结束。最常卡住的地方不是配置写法，而是权限、缓存、版本映射这三块——它们不出错时不显眼，一出就是“明明配对了却装不上”。