必须通过 repositories 字段手动声明源：vcs 类型用于有 composer.json 的 Git 仓库，package 类型用于无 composer.json 的老库，需严格匹配 name、version、dist 和 autoload 配置。
直接在 composer.json 中添加未托管到 Packagist 的库，必须绕过 Packagist 默认的包发现机制——核心是用 repositories 字段手动声明源，并确保该源支持 Composer 的安装协议（如 VCS 或 package 类型）。
使用 repositories 声明 Git 仓库（最常用场景）
当遗留库只存在于私有 Git 仓库（如 GitHub、GitLab、自建 Gitea）时，需显式配置 type: "vcs" 并提供完整 URL。Composer 会自动识别 composer.json（如果存在），否则无法安装。
- URL 必须可被本地机器 clone（SSH 或 HTTPS 均可，但 SSH 需提前配好密钥）
- 分支名必须是 Git 中真实存在的（如
master、main、legacy/v2.1），不能写错大小写 - 若仓库根目录没有
composer.json，需额外用package类型兜底（见下一条） - 不建议在
repositories中使用packagist.org镜像地址——它只代理已收录包，对未托管库无效
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/internal/legacy-lib"
}
],
"require": {
"internal/legacy-lib": "dev-main"
}
}
用 package 类型手动定义无 composer.json 的遗留库
很多老库根本没有 composer.json，此时只能靠 repositories.type: "package" 手动补全元信息。这是唯一能“硬塞”进 Composer 生态的方式，但后续维护成本高。
-
name和version必须符合 Composer 包命名规范（小写字母、短横线、点号，不能含下划线） -
dist必须指向可下载的压缩包（ZIP/TAR），且解压后路径结构要与autoload配置匹配 -
autoload推荐用"classmap": ["src/", "lib/"]，避免依赖 PSR-4 命名空间（老库通常不遵守） - 每次升级都要手动改
version和dist.url，无法自动更新
{
"repositories": [
{
"type": "package",
"package": {
"name": "vendor/old-utils",
"version": "1.2.0",
"dist": {
"url": "https://example.com/archives/old-utils-1.2.0.zip",
"type": "zip"
},
"autoload": {
"classmap": ["."]
}
}
}
],
"require": {
"vendor/old-utils": "1.2.0"
}
}
加载失败常见错误及定位方法
执行 composer install 或 composer require 报错时，优先检查是否命中以下典型问题：
-
[RuntimeException] Failed to execute git clone ...：SSH 权限不对，或 HTTPS 地址需要 token；用git clone手动测试是否可达 -
Could not find package vendor/name at any version：name拼写与repositories中声明的不一致，或version格式非法（如写成v1.0而非1.0.0） - 类找不到（
Class not found）：autoload路径没覆盖实际文件位置，或composer dump-autoload没重新生成映射 - 依赖冲突提示模糊：用
composer why-not vendor/package:version查具体阻塞链
真正麻烦的不是加仓库，而是让 Composer “相信”那个没有标准元数据的老库能被安全依赖——所有手动补全的信息（版本、自动加载、依赖声明）都得你来负责准确性和时效性。
