composer 的 repositories 配置必须用 vcs 类型，不能写成 package 或 composer；gitee 是 git 托管平台，需声明 vcs 仓库源，url 必须为带 .git 后缀的 https 地址，私有库需用 personal access token 配 auth.json，依赖版本须匹配分支（如 dev-main）或语义化 tag（如 v1.0.0），且仓库根目录 composer.json 的 name 字段须与 require 完全一致。
Composer 的 repositories 配置必须用 vcs 类型，不能写成 package 或 composer
Gitee 是 Git 仓库托管平台，不是 Composer 包仓库（如 Packagist），所以不能直接靠 composer require 拉取私有或非 Packagist 上的包——必须显式声明一个 vcs 类型的仓库源。常见错误是把 Gitee 项目地址直接塞进 repositories 却没指定 "type": "vcs"，导致 Composer 完全忽略该配置。
正确做法是在项目根目录的 composer.json 中添加：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitee.com/your-username/your-package.git"
}
]
}
注意：url 必须是完整的 Git HTTPS 地址（带 .git 后缀），不能是网页地址（如 https://gitee.com/xxx/yyy）；否则 Composer 会报错 Failed to clone https://gitee.com/xxx/yyy, could not read packages from it。
拉取私有 Gitee 仓库时，auth.json 要配 token，不是账号密码
Gitee 不支持 Git over HTTPS 的基础认证（即用户名+密码），直接配 auth.json 用账号密码会失败，报错类似 Could not fetch https://gitee.com/xxx/yyy.git, enter your Gitee credentials 并卡住。
必须使用个人访问令牌（Personal Access Token）：
- 登录 Gitee → 右上头像 → 「设置」→ 「私人令牌」→ 新建 token，勾选
projects权限 - 在项目根目录创建
auth.json（或全局~/.composer/auth.json），内容为：
{
"http-basic": {
"gitee.com": {
"username": "your-token-here",
"password": ""
}
}
}
password 字段留空，username 填入 token 字符串。这是 Gitee 的认证要求，和 GitHub 的 token:x-oauth-basic 形式不同。
依赖版本号要匹配 Gitee 仓库的 Git 分支或 tag，不能瞎写 dev-main
Composer 会自动扫描 Gitee 仓库的分支名和 tag，并把它们映射为版本号。但有个关键限制：只有符合语义化版本格式的 tag（如 v1.2.0、1.2.0）才能被识别为稳定版；而 main、master、dev 这类分支名，必须显式写成 dev-main（注意前缀 dev-）才能拉取。
常见误操作：
- 写了
"your/package": "^1.0"，但仓库里只有main分支、没打任何 tag → Composer 找不到匹配版本，报错Could not find package your/package - 写了
"your/package": "dev-main"，但仓库分支实际叫develop→ 应改用dev-develop - 打了 tag
1.0.0，却在require里写"your/package": "1.0.0"（缺v）→ 实际应写"1.0.0"或"v1.0.0"，两者都行，但1.0会匹配不到v1.0.0（因为1.0是约束，不是精确值）
执行 composer update 前先运行 composer clear-cache
Gitee 仓库配置变更后，Composer 可能缓存了旧的包元数据（比如之前失败过，缓存了“找不到包”的结果），导致即使配置已修正，composer update 仍报同样错误。
稳妥做法是每次修改 repositories 或 auth.json 后，先清缓存再更新：
composer clear-cache composer update your/package --with-dependencies
如果仍失败，加 -vvv 参数看详细日志，重点关注 Reading composer.json of your/package (dev-main) 是否出现，以及 Git 克隆命令是否被正确触发。Gitee 的响应延迟略高，偶尔超时也会中断，可临时设 COMPOSER_PROCESS_TIMEOUT=600 提高超时阈值。
最常被忽略的是：Gitee 仓库的 composer.json 文件必须放在仓库根目录，且其中 name 字段（如 "your/package"）要和 require 里写的完全一致——大小写、斜杠、中横线都不能错。
