Gitee不是Composer包注册中心，直接配其网页URL会报错；正确做法是声明type为vcs、url为.git地址，并确保项目根目录有composer.json且含合法name与版本，再通过require引用dev-main等分支。
Composer install 不会从 Gitee 拉代码，它只读 composer.lock 里的确切版本和源地址，而 Gitee 默认不是 Composer 的合法包源（repository），直接配 Gitee 链接会报错 Could not parse version constraint 或 Repository not found。
为什么不能直接用 Gitee 仓库 URL 当作 Composer 包源
Gitee 是 Git 托管平台，不是 Composer 的包注册中心。Composer 的 require 字段认的是 Packagist.org 上已注册的包名（如 monolog/monolog），或你手动声明的 vcs 类型仓库 —— 但即使声明为 vcs，也必须满足：该仓库根目录下有有效的 composer.json，且版本号符合 SemVer 规范（如 v1.2.3、dev-main）。
常见误操作：
- 把 Gitee 项目主页 URL（如
https://gitee.com/xxx/mylib）直接写进repositories→ 报错No composer.json present - 写了
composer.json，但没打 Git tag 或没设dev-master分支 →install找不到可安装的版本 - 用了中文分支名（如
功能开发）→ Composer 解析失败，不支持 Unicode 分支作为版本别名
正确配置 Gitee 仓库为 Composer vcs 源的三步
前提：你的 Gitee 项目根目录已有 composer.json，内容至少包含 {"name": "vendor/name", "version": "1.0.0"} 或依赖声明。
步骤如下：
- 在项目根目录的
composer.json中添加repositories块，类型设为vcs，URL 填项目 `.git` 地址（不是网页地址）："repositories": [ { "type": "vcs", "url": "https://gitee.com/your-username/your-lib.git" } ] - 在
require中引用该包，格式为"vendor/name": "dev-main"（注意：vendor/name 必须与库中composer.json的name完全一致） - 运行
composer install前，确保本地没有composer.lock，或先删掉它 —— 否则 Composer 会跳过解析新源，直接按 lock 文件还原
私有 Gitee 仓库需要 token 认证时怎么配
Gitee 私有库通过 HTTPS 克隆时需认证，Composer 默认不传凭据。解决方式只有两种：
- 用 SSH 方式（推荐）：把
repositories.url改成git@gitee.com:your-username/your-lib.git，并确保本地~/.ssh/id_rsa.pub已添加到 Gitee 账户的 SSH Keys 中 - 用私人令牌（Personal Access Token）：在
auth.json里配置（文件位置：项目根目录或COMPOSER_HOME目录）：{ "http-basic": { "gitee.com": { "username": "your-username", "password": "your-personal-token" } } }其中password填你在 Gitee 设置 → 私人令牌里生成的 token（权限至少勾选repo）
注意：auth.json 不应提交到 Git，务必加进 .gitignore。
install 和 update 行为差异容易被忽略的点
composer install 的行为完全由 composer.lock 决定 —— 即使你改了 repositories，只要 lock 文件里记录的是旧源或旧版本，它就不会去 Gitee 拉新东西。
真正触发从 Gitee 拉取的，是以下任一动作：
- 首次运行
composer install（无 lock 文件） - 运行
composer update vendor/name（显式更新某包） - 删掉
composer.lock后再install
另外，Gitee 的 API 限流较严（尤其免费账户），频繁 update 可能触发 403 Forbidden，此时应优先用 install + 锁文件保障稳定性，而非每次都要重解析远程。
