composer怎么引用Gitea私有仓库_内部代码托管平台对接配置【教程】_网络技术

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://@gitea.example.com/owner/repo.git —— 注意 URL 编码特殊字符（如 /、+）

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 也无能为力。

# php # js # git # json # composer # github # 编码 # app # access # ssl # ai # gitee # Token # 接口 # internal # http # https # ssh # gitea

相关栏目：【网站优化151355 】【网络推广146373 】【网络技术251813 】【 AI营销90571 】