私有仓库必须在项目根目录composer.json中显式声明repositories数组，否则composer require会静默失败并报“Could not find package”；repositories须为JSON数组，type仅支持vcs/composer/path，url需匹配对应规范，且require的name和版本必须与私有包composer.json中逐字一致。
私有仓库必须在项目 composer.json 里显式声明 repositories
不写就完全没用，composer require 会静默失败，报 Could not find package，而不是提示“源没配”。很多人误以为改私有包自己的 composer.json 或全局配置就够了，其实 Composer 只读当前项目根目录下顶层 composer.json 的 repositories 字段。
repositories 必须是 JSON 数组，不能是对象；每项必须含 "type" 和 "url"；type 只能是 "vcs"、"composer" 或 "path"，写成 "git" 或 "github" 直接无效。
-
"type": "vcs"：用于 Git/SVN 等版本库，url填仓库地址（如git@github.com:org/pkg.git或https://gitlab.example.com/org/pkg.git） -
"type": "composer"：用于 Satis/Nexus/Artifactory 这类提供packages.json的服务端，url填其 HTTP 地址（如https://packages.internal） -
"type": "path"：用于本地目录，url必须是相对于主项目composer.json的路径，不带file://，末尾不能加/（如../my-utils，不是../my-utils/）
认证方式选 SSH 还是 HTTPS？关键看 Git 服务和部署环境
SSH 更适合开发机和 CI/CD 中长期稳定的访问，HTTPS + PAT（Personal Access Token）更适合容器化或临时环境，但要注意 PAT 权限范围（至少要 repo）。
用 SSH 时，必须确保：
- 本地已生成密钥（
ssh-keygen -t rsa -b 4096），且公钥已添加到 Git 平台的 Deploy Keys 或账户 SSH Keys 中 - 能手动执行
git clone git@github.com:org/pkg.git成功（否则 Composer 一定失败） -
url写成 SSH 格式（如git@github.com:org/pkg.git），不能混用 HTTPS 地址
用 HTTPS 时，auth.json 必须存在且权限为 600：
{
"http-basic": {
"github.com": {
"username": "token",
"password": "ghp_abc123..."
}
}
}
注意：auth.json 不能提交到 Git，应放在项目根目录或用户家目录（~/.composer/auth.json），且路径必须可被 Composer 读取。
require 的包名和版本必须与私有仓库 composer.json 严丝合缝
Composer 不校验目录是否存在，只比对 name 和 version 字段。大小写、斜杠、短横线全部敏感——"acme/utils" ≠ "Acme/Utils" ≠ "acme_utils"。
常见错误：
- 私有包
composer.json里"name": "acme/utils"，但require写成"acme/utils": "dev-main"—— 表面成功，实际加载的是 Packagist 上同名公开包（如果存在） - 未初始化 Git 仓库，却要求
"dev-main"：Git 分支名必须真实存在，git init && git add . && git commit -m "init"是最低要求 - 用
"*"或"^1.0"而非明确分支/标签：私有 VCS 仓库不支持语义化版本推断，必须指定dev-xxx、v1.0.0或1.0.x-dev
首次引入必须用 composer update，不是 install
composer install 只读 composer.lock，而新仓库和新包根本不在锁文件里，所以它什么都不会装。只有 composer update vendor/name（或全量 update）才会重新解析 repositories 并拉取元数据。
还有两个易忽略点：
- 如果私有包是
path类型，且希望代码修改实时生效，得在私有包自己的composer.json里加"options": {"symlink": true}；Windows 下必须管理员权限运行composer update，否则符号链接创建失败且无提示 - autoload 映射不会自动继承——即使包装进
vendor/，类也 require 手动配置autoload或autoload-dev，并运行composer dump-autoload
最常卡住的地方不是网络或权限，而是 name 匹配错、type 写错、或者压根忘了 update。检查顺序建议：确认 repositories 在项目根 composer.json → 检查 name 是否逐字一致 → 手动 git clone 验证 URL 可达 → 最后跑 composer update。
