必须用composer repo add添加自定义仓库，且Composer版本不低于2.5.0；支持Git、Composer源及Packagist兼容服务三类仓库添加，需注意别名合法性、URL结尾斜杠及强制清缓存验证。
在私有包开发、企业内网组件复用或对接非 Packagist 的第三方源时，必须通过 composer repo add 类命令向项目或全局配置中显式添加自定义仓库，否则 Composer 根本无法识别和拉取这些包。
确认当前 Composer 版本与支持能力
运行 composer --version，确保输出为 Composer version 2.5.0 或更高——低于 2.4.0 的版本不支持 repo add 子命令，会直接报 Command "repo" is not defined 错误。
若版本过低，先执行 composer self-update 升级；升级后仍无 repo 命令，说明你用的是旧版 Composer（如 1.x），必须卸载重装 2.5+ 版本。
添加私有 Git 仓库（推荐用于内部 PHP 组件）
方法一：使用 composer repo add（Composer ≥ 2.5.0）
第一步：进入项目根目录，确保已有 composer.json 文件
第二步：执行命令 → composer repo add my-internal-git vcs https://git.example.com/internal/utils.git
第三步：验证是否写入 → 运行 composer config repositories，输出中应包含 "my-internal-git": {"type": "vcs", "url": "https://git.example.com/internal/utils.git"}
注意：仓库别名 【my-internal-git】 必须是合法的 PHP 变量名（仅含字母、数字、下划线，不能以数字开头），否则后续 require 会解析失败。
添加自定义 Composer 仓库（如 Nexus、Artifactory 或镜像站）
方法一：全局添加阿里云全量镜像（覆盖默认 Packagist）
执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
方法二：项目级添加私有 Composer 源（不干扰全局）
执行 composer config repositories.my-private-repo composer https://packages.internal.company.com
这会在当前项目的 composer.json 中的 repositories 字段追加一条记录，URL 必须以 【/ 结尾】，否则请求路径拼接错误导致 404。
添加包托管平台仓库（Packagist 兼容格式）
适用于接入 Packagist.org 风格的私有索引服务，例如自建 Satis 或 Private Packagist 实例。
运行 composer repo add my-satis composer https://satis.example.com
这条命令等效于手动在 repositories 中添加：{"type": "composer", "url": "https://satis.example.com/"}，Composer 会自动补全末尾斜杠。
如果目标地址已带斜杠（如 https://satis.example.com/），命令仍可执行，不会重复添加。
验证仓库是否生效并立即测试拉取
执行 composer show -a | grep your-package-name，若返回结果含该包信息，说明仓库已识别；若无输出，检查 URL 是否可公开访问、是否启用 HTTPS、证书是否有效。
强制刷新元数据缓存 → composer clear-cache && composer update --no-install
这一步必须做，否则 Composer 仍从旧缓存读取包列表，新仓库形同虚设。
最后执行 composer require vendor/package-name:dev-main（替换为实际包名和分支），观察是否从你刚添加的仓库拉取 ZIP 包。
