Gitlab仓库需满足特定条件才能被Composer识别为可安装包：根目录含合法composer.json、版本标签符合语义化规范（如v1.0.0）、name字段格式为vendor/name且与项目路径一致；私有仓库须显式配置repositories并妥善处理认证（HTTPS用PAT或auth.json，SSH需配置密钥）；更新tag需清缓存（composer clear-cache）。
Gitlab 仓库必须启用 Composer 支持
Gitlab 本身不内置 Composer 包仓库服务，但支持通过 composer.json 的 repositories 字段直接拉取 Git 仓库（需满足特定结构）。关键不是“发布到 Gitlab”，而是让 Gitlab 仓库能被 Composer 正确识别为可安装的包——这要求仓库根目录存在合法的 composer.json，且版本标签符合语义化规范（如 v1.0.0、1.2.3）。
常见错误：推送了代码但没打 tag，或 tag 名不带 v 前缀（composer install 会报 Could not find package xxx at version 1.0.0）。
- 确保
composer.json中name字段格式为vendor/name（如"myorg/utils"），且与 Gitlab 项目路径一致（推荐保持相同） - 使用
git tag -a v1.0.0 -m "release"打标签，再git push --tags - Gitlab 项目需设为至少
internal或public（私有项目需配置认证）
在项目中声明 Gitlab 私有仓库
不能只靠默认 Packagist，必须显式告诉 Composer 去哪找你的包。有两种方式：
- 全局配置（推荐用于团队）：
composer config -g repositories.myorg '{"type":"vcs","url":"https://gitlab.example.com/myorg/utils.git"}' - 项目级配置（更安全）：在项目根目录
composer.json的repositories数组里加一项
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/myorg/utils.git"
}
],
"require": {
"myorg/utils": "^1.0"
}
}
注意：url 必须是 Git 克隆地址（https:// 或 git@gitlab...），不是网页地址；若用 HTTPS 且仓库私有，需提前配置 git config --global credential.helper store 或使用个人访问令牌（PAT）替换 URL 中的密码位。
私有仓库认证：HTTPS vs SSH
HTTPS 方式容易因凭据缺失失败（Failed to clone https://... fatal: could not read Username）；SSH 更稳定，但需确保运行 composer install 的机器已配置好 SSH key 并添加到 Gitlab 账户。
- HTTPS 推荐写法：
https://oauth2:<your_personal_access_token>@gitlab.example.com/myorg/utils.git - SSH 写法：
git@gitlab.example.com:myorg/utils.git，前提是ssh -T git@gitlab.example.com能通 - 避免把 token 硬编码在
composer.json中——应使用auth.json（位于COMPOSER_HOME目录下）统一管理凭据
{
"http-basic": {
"gitlab.example.com": {
"username": "oauth2",
"password": "your_actual_token_here"
}
}
}
为什么 composer update 不拉新 tag？
Composer 默认缓存包元数据（包括 tag 列表），即使你刚推了 v1.0.1，composer update 仍可能提示 “nothing to install or update”。这不是 Gitlab 问题，而是本地缓存未刷新。
- 执行
composer clear-cache是最直接解法 - 也可加
--with-dependencies强制重载依赖树 - 开发阶段建议加
"minimum-stability": "dev"和"prefer-stable": true，便于快速测试dev-main分支
真正麻烦的是混合使用多个私有仓库时的依赖解析冲突——Composer 会按 repositories 数组顺序查找，靠前的仓库若意外提供了同名包（哪怕版本不匹配），就会跳过后续仓库。顺序错了，连 clear-cache 都救不回来。
