Composer 支持引用 Gitea 私有仓库，但需手动配置 repositories 为 type: "vcs" 并指定 Git 克隆地址（如 https://gitea.example.com/owner/repo.git 或 git@gitea.example.com:owner/repo.git），HTTPS 方式须配置 Git 凭据或 PAT，SSH 方式需确保密钥可用且 Gitea 已启用 SSH 支持。
Composer 能引用 Gitea 私有仓库，但默认不支持，必须手动配置 composer.json 中的 repositories 并启用 Git 认证机制；否则会报 Could not fetch https://gitea.example.com/api/v1/repos/xxx/yyy: 401 Unauthorized 或 Failed to download xxx/yyy from source: Failed to execute git clone。
在 composer.json 中声明 Gitea 仓库类型为 vcs
Gitee、GitHub 等平台可被 Composer 自动识别，但 Gitea 不在默认白名单中，必须显式声明仓库类型为 vcs，并指定完整 Git 克隆地址（不是 API 地址）。
-
type必须设为vcs，不能用package或composer -
url必须是可被git clone直接使用的 SSH 或 HTTPS Git 地址（如https://gitea.example.com/owner/repo.git或git@gitea.example.com:owner/repo.git），不是 Web 页面或 API 路径 - 若用 HTTPS，后续需配置 Git 凭据或使用个人访问令牌（PAT）；SSH 则需提前配好密钥和
known_hosts
{
"repositories": [
{
"type": "vcs",
"url": "https://gitea.example.com/your-org/internal-lib.git"
}
],
"require": {
"your-org/internal-lib": "^1.2"
}
}
HTTPS 方式必须配置 Git 凭据或 PAT（推荐用 token）
Gitea 默认关闭匿名克隆，HTTPS 请求需带认证。Composer 本身不传用户名密码，依赖 Git 的凭据系统或 URL 内嵌凭证 —— 后者不安全且易泄露，应避免。
- 生成 Gitea 个人访问令牌（Settings → Applications → Manage access tokens），勾选
read_repository（或repo）权限 - 将令牌写入 Git 凭据：运行
git config --global credential.helper store，然后执行git ls-remote https://YOUR_TOKEN@gitea.example.com/owner/repo.git触发凭据保存 - 或者直接在
composer.json的url中临时测试（仅限开发环境）：https://—— 注意 URL 编码特殊字符（如@gitea.example.com/owner/repo.git /、+）
SSH 方式需确保系统级 Git 可无交互克隆
SSH 更安全，但 Composer 调用的是系统 git 命令，不是 PHP 内置函数，所以一切依赖本地 Git 环境是否就绪。
- 确认能手动运行
git clone git@gitea.example.com:owner/repo.git成功（包括首次连接时自动写入~/.ssh/known_hosts） - 私钥不能有密码（或已用
ssh-agent加载），否则 Composer 会卡住等待输入 - Gitea 服务端需开启 SSH 支持，且用户已将公钥添加到 Gitea 账户（SSH Keys 设置页）
- URL 必须用
git@gitea.example.com:owner/repo.git格式（冒号分隔），不能用ssh://前缀，否则 Composer 无法识别
常见失败原因与验证步骤
配置完别急着 composer install，先逐层验证链路是否通：
- 用
git ls-remote https://gitea.example.com/owner/repo.git测试 Git 层是否能读取 refs（HTTPS + 凭据 / SSH + 密钥） - 运行
composer config --list | grep -i repo确认repositories已加载（注意 Composer 会合并全局和项目级配置） - 加
-vvv参数运行composer update your-org/internal-lib，看日志中是否出现Executing command (CWD): git clone --no-checkout及其返回码 - 若提示
Source dist not available，说明 Composer 尝试走 ZIP 下载（Gitea 不提供该接口），必须确保vcs类型生效且 Git 可用
最常被忽略的是：Gitea 实例启用了自签名 HTTPS 证书，而系统 Git 未配置 http.sslVerify false（不推荐）或未将 CA 加入信任链 —— 此时 git clone 直接失败，Composer 也无能为力。
