repositories必须写在composer.json顶层，type必须为"vcs"而非"git"；url须含.git后缀且与auth.json域名key一致；需同级声明"packagist.org": false禁用默认源；require包名须与私有库composer.json中name字段逐字符一致。
repositories 必须写在顶层，且 type 不能是 "git"
Composer 只在 composer.json 最外层读取 repositories 数组，塞进 config、extra 或 scripts 里等于没写。每项必须显式声明 "type": "vcs"——写成 "git"、"package" 或留空都会被静默忽略。
常见错误示例：
-
"type": "git"→ 改为"type": "vcs" -
"url": "https://gitlab.example.com/group/repo"（缺.git）→ 改为"https://gitlab.example.com/group/repo.git" -
"url": "https://gitlab.example.com/group/repo.git"但域名和auth.json中的 key 不一致 → 检查是否应为"gitlab.example.com"（不含端口/路径）
HTTPS 还是 SSH？选哪个更稳
SSH 更适合 CI/CD 和自动化环境：只要部署机的 ~/.ssh/id_rsa 已配好、公钥已加到 GitLab/GitHub 的 Deploy Keys，就无需 Token 管理或权限刷新。HTTPS 则依赖 Token 生命周期，且容易因 URL 编码、Basic Auth 拼接出错。
用 SSH 时注意：
-
url必须是完整克隆地址，如"git@gitlab.example.com:acme/utils.git" - 测试连通性：运行
ssh -T git@gitlab.example.com，看到Welcome to GitLab才算通 - 不要在
url里硬编码用户名或密码；Composer 不解析 SSH URL 中的凭证字段
require 包名必须和私有库 composer.json 的 name 字段逐字符一致
Composer 不按 Git 路径推导包名，只严格比对私有库根目录下 composer.json 里的 "name" 字段。差一个字母、大小写、分隔符（/ vs -），就会报 Could not find package。
假设私有库的 composer.json 是：
{
"name": "acme/utils",
"version": "1.0.0"
}
那主项目 require 必须写：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
"acme/utils": "dev-main"
以下全部无效：
-
"Acme/utils"（大小写错） -
"acme-utils"（用了短横线） -
"utils"（漏 vendor 段） -
"acme/utils": "main"（缺dev-前缀，会被当模糊约束去 Packagist 查）
不关 packagist.org，私有包永远不生效
哪怕你写了三行 repositories，只要没显式禁用默认源，Composer 就会优先查 packagist.org，查不到才 fallback——而 fallback 不触发 VCS 解析，直接报错。
必须在 composer.json 顶层加这一行：
"packagist.org": false
注意：
- 不是
"packagist": false，也不是"packagist.com" - 它和
repositories同级，不是其子项 - Artifactory/Satis 等 Composer 类型源也必须配这个，否则照样走外网
最易被忽略的是：URL 末尾斜杠、auth.json 权限 600、以及私有库自身 autoload 段缺失——这三者会让包装进 vendor 却无法 new 实例。
