Composer 可引用 Gitee 包但需手动配置 vcs 仓库源，目标仓库须含合规 composer.json（name 为 vendor/package 格式）、确保权限（SSH 或 PAT 认证），并强制 --prefer-source 安装以防 dist 下载失败。
Composer 可以直接引用 Gitee 上的包，但默认不支持，必须手动配置 repositories（仓库源）并确保包符合 Composer 包规范（含 composer.json）。
确认 Gitee 仓库是否具备 Composer 包结构
不是所有 Gitee 项目都能被 composer require 安装——它必须是“可安装的包”，即：
- 根目录下有有效的
composer.json文件（至少含name和version或autoload） -
name字段需遵循vendor/package格式（如myorg/my-utils），不能是纯中文或非法字符 - 若使用私有仓库，还需确保你有对应访问权限（SSH 或 Personal Access Token）
在 composer.json 中添加 Gitee 仓库源
Gitee 不是 Packagist 官方镜像，所以必须显式声明为 vcs 类型仓库。注意：不要用 https://gitee.com/xxx/yyy.git 直接写进 repositories —— 这是常见错误。
正确做法是只写 Gitee 的域名 + 用户/组织名，让 Composer 自动发现子路径：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitee.com/myorg"
}
],
"require": {
"myorg/my-utils": "dev-main"
}
}
其中 myorg/my-utils 必须与目标仓库 composer.json 中的 name 完全一致；dev-main 表示安装 main 分支（Gitee 默认主分支名，非 master）。
处理私有仓库或需要认证的场景
如果 Gitee 仓库是私有的，或者你遇到 401 Unauthorized、Could not fetch 等错误，Composer 默认不会走你的 Git 凭据。解决方式有两种：
- 用 SSH URL 替代 HTTPS：把
url改成git@gitee.com:myorg/my-utils.git，并确保本地已配置 SSH key 且能ssh -T git@gitee.com成功 - 用 Gitee Personal Access Token（推荐）：在
auth.json中配置（项目根目录或全局~/.composer/auth.json）
{
"http-basic": {
"gitee.com": {
"username": "your_gitee_username",
"password": "your_personal_access_token"
}
}
}
Token 需在 Gitee →「设置 → 私人令牌」中创建，勾选 repo 权限即可。
避免 dev-main 被自动降级为 dist 包导致失败
Composer 默认优先下载压缩包（dist），但 Gitee 不提供标准 dist ZIP 下载地址，会导致安装中断或报错 Failed to download myorg/my-utils。强制走源码安装：
- 运行
composer install --prefer-source或composer require myorg/my-utils --prefer-source - 或在
composer.json顶层加"prefer-stable": false和"minimum-stability": "dev"（仅开发环境建议）
更稳妥的做法是在 config 中锁定行为：
{
"config": {
"preferred-install": {
"myorg/*": "source"
}
}
}
Gitee 的 vcs 仓库支持有限，分支名、tag 解析不如 GitHub 稳定；如果包长期维护，建议同步打正式 1.0.0 这类语义化 tag，并在 composer.json 中明确指定版本而非依赖 dev-main —— 否则下次 main 分支变，项目可能悄无声息地崩掉。
