Composer 安装 Gitee 包需在项目 composer.json 中配置 vcs 类型仓库并确保包含合法 composer.json、正确 name 字段、PSR-4 自动加载及有效版本标识（tag 或分支），否则会报错找不到包或类未找到。
Composer 不能直接“下载 Gitee 上的 PHP 包”，除非该包已正确发布为 Composer 可识别的包（即有 composer.json、遵循 PSR-4 自动加载、有稳定版本标签或分支），且你配置了正确的仓库源或直接引用 —— 否则 Composer 会报 Could not find package xxx 或 no matching package found。
怎么让 Composer 安装 Gitee 上的私有/非 Packagist 包
核心是告诉 Composer：这个包不在 Packagist，而是在 Gitee 的某个 Git 仓库里。需在项目根目录的 composer.json 中显式声明 repositories，并指定 type: "vcs"：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitee.com/username/my-php-package.git"
}
],
"require": {
"username/my-php-package": "dev-main"
}
}
注意点：
-
url必须是可公开克隆的 HTTPS 地址（如含敏感信息，改用 SSH +git@gitee.com:...并配好 SSH key） - 包名
username/my-php-package必须与该仓库中composer.json里的"name"字段完全一致 - 版本号（如
"dev-main"）必须对应仓库中存在的分支名或 tag 名；Gitee 上没打 tag 就只能用dev-xxx分支名 - 如果仓库里没有
composer.json，Composer 会直接拒绝安装
Gitee 仓库如何支持 Composer 安装
不是所有 Gitee 仓库都能被 Composer 安装，必须满足最低结构要求：
立即学习“PHP免费学习笔记（深入）”；
- 根目录下有合法的
composer.json（至少含name和autoload） -
autoload推荐用"psr-4"，例如："autoload": { "psr-4": { "MyPackage\\": "src/" } } - 要有明确的版本标识：打 Git tag（如
v1.0.0）或存在稳定分支（如main、master、dev） - 若用私有仓库（如企业版 Gitee），需在
auth.json中配置 token 或用户名密码（HTTPS 方式）
能不能把 Gitee 配成全局镜像源（类似 packagist.phpcomposer.com）
不能。Gitee 不是 Composer 的元数据源（metadata server），它不提供 packages.json 索引、不支持 search、不兼容 Packagist 协议。所谓“配置码云仓库地址”是个常见误解 —— 你无法把 Gitee 当作 Packagist 替代品全局启用。
唯一可行的“全局”操作，是用 composer config -g repositories.xxx 添加个别常用私有包源，但依然只对这些特定包生效，不影响其他包的解析逻辑。
顺带提醒：composer config -g repo.packagist composer https://packagist.org 这类命令和 Gitee 无关，别混淆。
常见错误和绕不过去的坑
实际操作中最容易卡在这几个地方：
- 执行
composer require username/my-php-package报错Could not find package：大概率是repositories没写进当前项目的composer.json，或写错位置（不能放在require里） - 报错
Failed to download ... The authenticity of host 'gitee.com' can't be established：说明用了 SSH 但本地没配好 known_hosts，换 HTTPS 或手动ssh -T git@gitee.com初始化 - 安装后类找不到（
Class not found）：检查仓库中composer.json的autoload路径是否和实际文件结构匹配，运行composer dump-autoload强制重生成映射 - 想安装未打 tag 的最新提交，却只写
"dev-main"还不行：加上"minimum-stability": "dev"和"prefer-stable": false到composer.json
最麻烦的一点其实是：Gitee 仓库的维护者得自己管好 composer.json 和版本标签，下游使用者几乎没法绕过这点强行安装。
