--repository-url仅替换元数据源，不参与包发现；必须通过repositories声明+require显式指定同名包才能生效，且version需可解析、name须完全匹配。
只能通过 repositories 配置块 + require 显式指定包名，才能让某个包走自定义源；光改全局源或用 --repository-url 不起作用。
为什么 --repository-url 对单个包无效
这个参数只替换元数据获取地址（即 packages.json），但 Composer 仍会按 composer.json 中声明的包名去原源查版本信息。如果你要的包不在那个镜像里（比如私有包、未同步的 dev 分支），就会 fallback 到 packagist.org 或直接报错。
常见错误现象：Could not find package vendor/package at any version，即使你加了 --repository-url http://my-git.internal。
- 根本原因：Composer 不会把
--repository-url当作“候选源列表”，它只当“唯一元数据源” - 正确思路：把自定义源作为
repositories的一部分，让它参与包发现过程 - 必须配合
require使用——不能靠install自动拉取，得明确写进依赖声明里
repositories 中 type 选 vcs 还是 package
取决于你控制的是源代码还是预构建包：
-
"type": "vcs"：适用于 Git/Svn/Hg 仓库，Composer 会自动识别分支、tag、commit，支持dev-main、v1.2.3等写法，推荐用于开发中调试或 fork 后 patch -
"type": "package"：适用于没有 composer.json 的 ZIP 包、内部 PHP 工具库、或需要手动声明版本信息的场景；必须手写version、dist.url、autoload等字段，否则 autoload 失效 - 别混用：一个仓库 URL 只能配一种 type；如果同时有 Git 和 ZIP，得拆成两个 repository 条目
示例（vcs）：
"repositories": [
{
"type": "vcs",
"url": "https://github.com/myorg/internal-sdk.git"
}
]
require 时怎么写包名和版本才命中自定义源
包名必须和自定义源中 composer.json 的 name 字段完全一致；版本必须存在且可解析。
- Git 仓库：用
dev-branch或dev-commit-hash，例如composer require myorg/internal-sdk:dev-main - 如果仓库没设默认分支（如无
main或master），得显式写dev-develop，否则报Could not find a branch or tag matching 'dev-main' - 私有 Git 用 SSH？确保
git@github.com:myorg/internal-sdk.git能本地git clone成功，否则 Composer 会卡在Failed to execute git clone - 别依赖
latest：vcs 源不提供 “latest-stable” 元数据，composer require myorg/internal-sdk（不带版本）大概率失败
容易被忽略的权限与缓存问题
配置完 repositories 和 require，运行 composer update myorg/internal-sdk 仍失败？先检查这几处：
- 是否清过缓存：
composer clear-cache—— Composer 会缓存 vcs 仓库的 tags/branches 列表，改了远程分支后旧缓存会导致找不到新 tag - SSH 密钥是否加载：
ssh -T git@github.com要能通；若用 HTTPS，确认是否需 token（https://token:x-oauth-basic@github.com/...） - 仓库的
composer.json是否合法：json_decode(file_get_contents('composer.json'), true)不报错，且含"name"和"version"（vcs 源可省略 version，但 package 源必须有） - 别漏掉
composer update的包名参数：写composer update全量更新可能跳过你的包，因为它的版本约束没变；务必加具体包名
最稳验证方式：composer show myorg/internal-sdk 输出里出现 source 字段且 URL 是你配的仓库地址，才算真正走对了源。
