根本原因是项目级repositories数组会默认关闭隐式packagist.org源，需显式添加{"type":"composer","url":"https://packagist.org","packagist":false}兜底；vcs url必须可git clone且含.git后缀；私有源必须返回合法packages.json。
composer.json里加了repositories但require不生效
根本原因不是配置写错了，而是 Composer 默认关闭了 packagist.org 的隐式源——哪怕你只加了一条 vcs 仓库，它也不会再去查 Packagist，除非你显式告诉它“这个包该去哪找”。
常见表现：composer require myorg/internal-sdk 报 Could not find package，但手动 git clone https://gitlab.example.com/myorg/internal-sdk.git 能成功。
- 必须在
repositories数组里加一条兜底项：{"type": "composer", "url": "https://packagist.org", "packagist": false}（注意不是删掉，是显式禁用） - 更稳妥的做法：把私有源放数组最前面，再补上带
"packagist": false的 Packagist 条目，确保路由可控 - 别依赖全局配置；
composer config -g repositories和项目级composer.json冲突时，后者完全屏蔽前者
vcs类型URL填错导致静默失败
Composer 对 vcs 类型的 url 字段校验极严，填错不会报网络错误，而是直接跳过该仓库、不提示原因。
典型错误："url": "https://github.com/myorg/sdk"（缺 .git 后缀）、"url": "https://github.com/myorg/sdk/releases/tag/v1.2.0"（是 HTML 页面，不是 Git 地址）。
-
url必须是能被git clone直接消费的地址，例如https://gitlab.example.com/myorg/sdk.git或git@git.example.com:myorg/sdk.git - HTTPS 方式带 token 的写法（如
https://token:x-oauth-basic@...）在 Composer 1.10+ 已弃用，凭证必须走auth.json - 验证方式：新开终端执行
git ls-remote -h https://gitlab.example.com/myorg/sdk.git，能列出分支才算真正可达
require里版本号写法不匹配Git实际结构
vcs 仓库不靠 packages.json 提供版本列表，而是动态解析 Git 引用。写错版本字符串，Composer 就找不到对应 commit。
现象：dev-main 报错说 no matching package found，但仓库明明有 main 分支。
-
dev-main要求仓库存在main分支，且该分支根目录下composer.json的"name"字段必须严格等于require中写的包名（如"myorg/sdk"） - 用 tag 版本（如
"1.2.3"）时，tag 必须真实存在，且该 tag 指向的composer.json中"version"值必须字面量匹配（不能是"v1.2.3"或"1.2.3-beta"） - commit hash 写法为
dev-main#abc123，不是abc123单独写；latest、master这类非标准标识符一律无效
CI/CD环境git命令缺失或权限异常
Composer 在 --prefer-source、dev- 版本或 vcs 仓库场景下，必须调用系统 git 命令。CI 环境常因精简镜像导致失败。
典型报错：sh: git: not found 或 fatal: Could not read from remote repository。
- Docker 镜像中务必安装完整 git：Debian/Ubuntu 用
RUN apt-get install -y git，Alpine 用RUN apk add --no-cache git - SSH 认证场景下，CI 必须加载私钥并运行
ssh-agent；HTTPS 场景下，auth.json文件需提前注入容器且权限设为600 - 调试建议：在 CI 步骤开头加
git --version和composer diagnose，确认Git binary found at行输出路径有效
最易被忽略的一点：所有 vcs 仓库的 url 必须指向一个**含合法 composer.json 的 Git 仓库根目录**，且该文件里的 name、autoload 等字段不能空——Composer 不会帮你生成元数据，它只做精确匹配。
