私有源必须置于repositories数组首位并显式添加{"packagist.org": false}，否则Composer优先查询公网源导致私有包无法命中；type须为vcs或composer，URL需规范（.git或/结尾），数组须为索引形式，auth.json路径权限结构须严格匹配。
必须把私有源放在 repositories 数组首位，并显式禁用 packagist.org，否则 Composer 永远先查公网、你的私有包根本不会被尝试拉取。
私有源必须置顶且 type 为 vcs 或 composer
Composer 查包是线性遍历 repositories 数组，遇到第一个返回 “包不存在” 的源就停，不再往后看。如果你把阿里云镜像或 Packagist 镜像放前面，myorg/internal-sdk 就会直接报 Could not find package，连认证步骤都进不去。
正确写法是：
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.internal/myorg/internal-sdk.git"
},
{
"type": "composer",
"url": "https://repo.internal/"
},
{
"packagist.org": false
}
]
-
type必须是vcs（GitLab/GitHub）或composer（Satis/Artifactory），不能写成git或留空 - HTTPS 地址末尾必须带
.git；Satis/Artifactory 地址末尾必须带/ - 数组必须是索引形式，不能写成对象键值对（如
"internal": { ... }），否则只读第一个
auth.json 路径、权限、结构三者缺一不可
Composer 不读 Git 凭据，也不走 SSH agent（vcs 模式下），只认 auth.json，且只在两个固定路径生效：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Linux/macOS：
~/.composer/auth.json（不是项目根目录） - Windows：
%APPDATA%\Composer\auth.json - 权限必须设为
600：运行chmod 600 ~/.composer/auth.json，否则静默忽略 - 结构必须严格匹配域名：若 URL 是
https://gitlab.internal/group/repo.git，key 就只能是"gitlab.internal"，不能带端口、协议或路径 - GitLab 用
http-basic字段，password填glpat-xxx；GitHub 用github-oauth；Bitbucket 必须用 App Password
require 中的包名必须和私有库 composer.json 的 name 字段逐字符一致
Composer 不按 Git 路径推断包名，只比对私有库自身 composer.json 里的 "name" 字段。差一个字母、大小写、斜杠或连字符，就失败。
- 私有库中写的是
"name": "acme/utils"，主项目require就必须是"acme/utils": "dev-main" - 不能写成
"Acme/utils"、"acme-utils"、"acme/utils-dev"，也不能省略 vendor 段 - 分支引用必须加
dev-前缀："dev-main"可行，"main"或"*"会被当模糊约束去 Packagist 查，必然失败 - 确认私有库根目录的
composer.json已正确定义name，且无拼写错误或不可见字符
验证是否真走私有源：用 --verbose 看 dist.url
执行 composer show acme/utils --verbose，关键看输出里 dist.url 是否指向你的私有地址（如 https://gitlab.internal/acme/utils.git），而不是 https://api.github.com/repos/... 或 https://packagist.org/p/...。
- 如果看到
dist.url是 Packagist 地址，说明"packagist.org": false没生效，或没写在repositories数组里 - 如果卡在
Cloning或报Authentication failed，优先检查auth.json路径和权限，再手动跑git clone https://gitlab.internal/acme/utils.git验证地址是否可访问 - CI/CD 中推荐用
COMPOSER_AUTH环境变量传入凭证 JSON，避免文件落盘或权限问题
最常被忽略的是 "packagist.org": false 的位置——它必须是 repositories 数组里的一个独立对象项，不是顶层字段，也不是嵌套在某个仓库配置里。少这一行，所有配置都白搭。
