Gitee私有仓库需在composer.json的repositories字段中用vcs类型声明Git克隆地址（如https://gitee.com/user/repo.git），并打tag或用dev-branch as 1.0.x-dev方式指定版本，HTTPS需配置Personal Access Token认证。
composer.json 里怎么加 Gitee 私有仓库
必须用 repositories 字段手动声明，不能靠全局配置或 Composer 默认行为自动识别。Gitee 私有库本质是 Git 仓库，Composer 不会主动扫描你的 Gitee 账号下所有项目，得明确告诉它“这个 URL 是一个包源”。
常见错误是把 Gitee 项目主页 URL（比如 https://gitee.com/username/my-package）直接塞进 repositories —— 这不行，必须用 Git 克隆地址（git@gitee.com:username/my-package.git 或 https://gitee.com/username/my-package.git），否则 composer install 会报 Failed to download username/my-package 或卡在“Loading from cache”不动。
- 用 SSH 地址（
git@gitee.com:username/my-package.git）前提是你本地已配好 SSH key 并添加到 Gitee 账户 - 用 HTTPS 地址（
https://gitee.com/username/my-package.git）需确保 Composer 能走认证：要么用git config --global credential.helper store缓存凭据，要么在 URL 里嵌用户名密码（不推荐，尤其提交到 Git） -
type必须设为vcs，不是package或composer
示例片段：
"repositories": [
{
"type": "vcs",
"url": "https://gitee.com/your-org/internal-sdk.git"
}
]
私有包的 version 怎么写才不会被跳过
Composer 默认只认带稳定版本号（如 v1.0.0、1.2.3）或符合语义化版本规则的 Git tag。如果你的 Gitee 仓库只有 main 或 dev 分支，没打任何 tag，composer require your-org/internal-sdk 会失败，提示 Could not find package ... in a version matching ...。
解决方法只有两个，且必须二选一：
- 在 Gitee 仓库打正式 tag：用
git tag v1.0.0 && git push origin v1.0.0，然后require时指定"your-org/internal-sdk": "^1.0" - 不打 tag，改用分支别名：在
composer.json的require里写"your-org/internal-sdk": "dev-main as 1.0.x-dev"，前提是仓库有main分支；注意as后面的版本号必须带-dev后缀，否则会被认为是稳定版而拒绝安装
别名方式适合开发阶段，但上线前务必切到真实 tag，否则部署环境可能因 minimum-stability 设置拉不到 -dev 包。
为什么 composer install 一直卡在 “Updating dependencies”
大概率是 Git 认证失败导致 Composer 在后台反复重试 SSH 或 HTTPS 请求，表面看是卡住，实际是静默等待输入密码或超时重连。Gitee 对未认证的 HTTPS 请求会返回 404（而非 401），Composer 就误判为“仓库不存在”，转而查 Packagist，造成延迟和混淆。
排查步骤很直接：
- 手动执行
git ls-remote -h https://gitee.com/username/my-package.git（或对应 SSH 命令），看是否能列出分支 —— 不能就说明本地 Git 环境没通 Gitee - 检查
~/.composer/auth.json是否有 Gitee 凭据（HTTPS 场景），格式要严格：
{
"http-basic": {
"gitee.com": {
"username": "your-gitee-username",
"password": "your-personal-access-token"
}
}
}
注意：Gitee 不支持账户密码直连，必须用「私人令牌（Personal Access Token）」代替密码，且该 token 需勾选 repo 权限。
CI/CD 环境下如何安全拉取私有包
本地能跑不等于 CI 能跑。GitLab CI、GitHub Actions 或私有 Jenkins 上，缺失 SSH key 或 auth.json 是最常见断点。
关键动作只有三个，缺一不可：
- 在 CI 配置中注入 Gitee 私人令牌为环境变量（如
GITEE_TOKEN），不要硬编码 - 运行
composer config http-basic.gitee.com $GITEE_USERNAME $GITEE_TOKEN动态写入auth.json - 确保项目根目录的
composer.json中repositories指向的是 HTTPS 地址（SSH 在 CI 容器里通常没预装 key，HTTPS + token 更可控）
额外提醒：有些 CI 模板默认缓存 vendor/ 或 ~/.composer/cache，但缓存里不含认证信息，所以每次都要重新 config http-basic，不能省。
