composer私有仓库配置需满足五点：repositories必须顶层且type为"vcs"；gitlab url须为可clone地址并带.git；auth.json须放系统级路径、权限600、域名严格匹配；require包名与私有库composer.json的name字段逐字符一致；必须禁用packagist.org并把私有源置于repositories首位。
repositories 必须写在 composer.json 顶层且 type 为 "vcs"
Composer 只扫描 composer.json 最外层的 repositories 数组，嵌套在 config、scripts 或任意自定义字段里都无效。写成对象（如 "repositories": {}）或漏掉 "type": "vcs" 会导致静默忽略——不报错，也不拉包。
GitLab 仓库 URL 必须是可直接 git clone 的地址：
- HTTPS 格式：结尾必须带
.git，例如"https://gitlab.internal/acme/utils.git"；写成/acme/utils或/acme/utils/-/tree/main会触发No valid composer.json was found - SSH 格式：如
"git@gitlab.internal:acme/utils.git"，需确保本地ssh -T git@gitlab.internal能通，且 agent 已加载密钥
auth.json 必须放对路径、设对权限、域名严格匹配
Composer 不读项目目录下的 auth.json，只认系统级固定路径：
- Linux/macOS：
~/.composer/auth.json（注意是当前执行用户的家目录） - Windows：
%APPDATA%\Composer\auth.json - 权限必须为
600：chmod 600 ~/.composer/auth.json，否则直接跳过，且无任何提示
内容结构必须是 {"http-basic": {"gitlab.internal": {...}}}：
- 域名 key（如
gitlab.internal）必须和repositories.url中的 host 完全一致，不含协议、端口、路径；gitlab.internal:8080和gitlab.internal是两个不同 key - username 固定为
oauth2，password 填glpat-开头的 Personal Access Token
require 包名和版本必须与私有库 composer.json 逐字符一致
Composer 不推导包名，只硬匹配私有仓库根目录下 composer.json 的 name 字段：
batch-git-url-replace
下载
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
- 若私有库写的是
"name": "acme/utils"，主项目require就只能写"acme/utils": "dev-main" - 大小写、斜杠、下划线、vendor 段缺一不可；
"Acme/utils"、"acme-utils"、"utils"全部失败 - 分支名必须加
dev-前缀："dev-main"可行，"main"或"*"会被当模糊约束去packagist.org查，必然报Could not find package
必须显式禁用 packagist.org 否则私有包永远不命中
即使你写了私有源，Composer 默认仍会 fallback 到 packagist.org 查询——查不到才继续往后找，但私有包根本不会被匹配到。
正确做法是在 repositories 数组里紧接私有项后添加：
{"packagist.org": false}
这行不能省略，不能放在数组外，也不能写成顶层键；漏掉它，整个私有依赖流程就静默失效。
最容易被忽略的是：私有源必须放在 repositories 数组最前面，否则线性匹配机制会让前面的镜像源先返回“不存在”，后续私有源根本不会被访问。
