私有仓库需在composer.json的repositories数组中显式声明，type必须为vcs/composer/path且含正确url，包名大小写须与require完全一致，认证凭据仅限600权限的auth.json或COMPOSER_AUTH环境变量。
私有仓库必须在项目根目录的 composer.json 里显式声明 repositories，否则 composer require 一定失败——Composer 不会自动发现你内网或 Git 上的包，连试都不会试。
repositories 字段必须是数组，且 type 不能写错
常见错误是把 repositories 写成对象（比如 {"my-vcs": {...}}），或者漏掉 "type": "vcs"。Composer 只认 JSON 数组，每个仓库项必须含 type 和 url：
-
type必须是vcs（Git/SVN/Hg）、composer（如 Satis 服务）或path（本地开发用），不能写成git或github -
url要指向 Git 仓库根目录（即包含composer.json的那个地址），不是某个分支页或 tag 页 - 如果混用多个源，顺序决定优先级：Composer 从上到下扫描，匹配第一个就停，后面的同名包被忽略
- 要禁用 Packagist 默认源，必须加一项
{"packagist.org": false}，不能塞进其他仓库对象里
认证凭据只能放 auth.json，且权限必须是 600
auth.json 是唯一合法载体，硬编码到 composer.json 或 URL 里（如 https://token:xxx@...）会被拒绝或泄露。它必须放在项目根目录（与 composer.json 同级）或全局路径，且权限严格为 600：
- HTTP Basic 认证（如私有 GitLab）走
http-basic字段，域名填gitlab.example.com，不是完整 URL - GitHub 私有库推荐
github-oauth+ Personal Access Token（scope 至少含read:packages） - SSH 方式（
git@gitlab.com:org/repo.git）不依赖auth.json，但要求部署机已加载对应密钥到ssh-agent - CI 环境建议用
COMPOSER_AUTH环境变量注入 JSON 凭据，避免挂载文件出错
vcs 类型下，版本号实际来自 Git tag，不是 composer.json 的 version 字段
Composer 解析 vcs 包时，完全忽略 composer.json 里的 version 值。它只认 Git 的 tag 和分支名：
- 想用
"^1.0"，就必须打v1.0.0或1.0.0这样的语义化 tag；v1.0或1.0不被识别 - 分支名如
main对应虚拟版本dev-main，require 时得写"dev-main"，且需"minimum-stability": "dev" - 没打任何 tag 时，
dev-main是唯一可用选项；写"1.0.0"会报Could not find package ... at version 1.0.0 - 别用
package类型硬编码单个包——维护成本高，无法随 Git 更新
require 中的包名必须和私有仓库 composer.json 的 name 字段完全一致
大小写敏感，多一个空格、少一个下划线都不行。这是最常被忽略的匹配点：
- 假设私有仓库
composer.json里写的是"name": "myorg/utils"，那require里必须写"myorg/utils"，不能写成"MyOrg/utils"或"myorg-utils" - 如果用了
path类型（本地联调），url指向的目录里也必须有合法composer.json，且name仍要匹配 - 包名冲突时，靠
repositories顺序控制：把私有源放 packagist.org 前面，才能确保拉到你自己的版本 - 执行完
composer require后，检查vendor/下是否真生成了对应目录；没生成说明根本没匹配上源，不是认证问题
真正卡住的地方往往不是“怎么配”，而是“配了但没生效”——比如 repositories 放错了位置、auth.json 权限不对、或者包名大小写差了一位。这些地方没有报错提示，只会静默跳过。动手前先确认这三点：数组格式对不对、auth.json 在不在项目根目录且 ls -l 看过权限、私有包的 name 和 require 里写的是否一字不差。
