私有仓库必须在composer.json的repositories字段中声明，type设为vcs，url指向含composer.json的Git根目录；auth.json需置于项目根目录且权限为600，按http-basic或github-oauth配置凭证；版本依赖Git tag而非composer.json中的version字段。
私有仓库必须用 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是否生效
