必须显式声明 type 为 vcs，url 使用 HTTPS（推荐含令牌）或 SSH，且需确保 Gitea API 可访问、认证有效、分支标签信息能被正确返回。
composer.json 里怎么写 Gitea 私有仓库的 repository 配置
必须显式声明 type 为 vcs，且 url 要用 SSH 或 HTTPS（推荐 HTTPS + 个人访问令牌），不能只写 Gitea 页面上的 Web 地址。Gitee/GitLab 风格的自动发现不适用于 Gitea，默认不会扫描用户/组织下的所有仓库。
-
url必须是可被git clone直接使用的地址，例如https://gitea.example.com/your-org/your-package.git或git@gitea.example.com:your-org/your-package.git - 如果用 HTTPS，需提前在本地配置 Git 凭据（
git config --global credential.helper store）或在 URL 中嵌入令牌：https://token:x-oauth-basic@gitea.example.com/your-org/your-package.git - SSH 方式需确保
~/.ssh/id_rsa.pub已添加到 Gitea 账户的 SSH Keys 中，且git@gitea.example.com能被正常解析和连接
为什么 composer install 报 “Could not fetch” 或 “Repository not found”
常见原因是认证失败或 Gitea 实例未启用 API 访问支持。Composer 在拉取包前会先调用 Gitea 的 REST API（如 /api/v1/repos/{owner}/{repo}）探测仓库元信息，若返回 404 或 401，就会中止并报错，哪怕 git clone 本身能成功。
- Gitea 管理员需确认
ENABLE_REPO_UNITS和DISABLE_HTTP_GIT配置不影响 API 可达性 - 检查 Composer 是否用了代理：某些企业网络会拦截
api/v1路径，但放行.git流量，此时应设"secure-http": false并改用 SSH - 运行
composer config -g github-oauth.gitea.example.com your_token不起作用 —— 这个配置只对 GitHub 生效，Gitea 必须走http-basic或环境变量
如何让 composer 正确识别 Gitea 仓库里的分支和标签
Gitea 默认开启 Git 原生协议，但 Composer 依赖其 API 返回的 default_branch 和 tags 列表。若 API 返回空或格式异常（比如 Gitea 版本 "dev-main" 或 "v1.2.0"）。
- 升级 Gitea 至
v1.16+是最稳妥方案；旧版需手动在composer.json中加"branches": ["main", "develop"]等硬编码提示 - 确保 Gitea 仓库设置了正确的默认分支（Settings → Repository → Default Branch），否则
dev-master可能指向已删除的master - 打 Git tag 后需等待 Gitea 同步索引（通常几秒），立即
composer update可能查不到新标签
使用 private-packagist 或自建 Satis 时怎么对接 Gitea
不建议直接把 Gitea 当作 Packagist 源 —— 它没有 Composer 的 packages.json 生成能力。正确路径是：Satis 或 Private Packagist 作为中间层，定时从 Gitea 拉取代码并构建元数据。
{
"name": "my-company/internal-packages",
"repositories": [
{
"type": "package",
"package": {
"name": "my-company/auth-service",
"version": "dev-main",
"source": {
"url": "https://gitea.example.com/my-company/auth-service.git",
"type": "git",
"reference": "main"
}
}
}
],
"require": {
"my-company/auth-service": "dev-main"
}
}
这种方式绕过 API 探测，但失去自动版本发现能力；适合少量关键内部包。高频更新的项目仍应配 Satis，并在 satis.json 中明确列出 Gitea 仓库 URL。
真正容易被忽略的是 Gitea 的 REQUIRE_SIGNIN_VIEW 配置：如果开启，未登录状态下连仓库主页都 404，API 更不可达 —— 此时即使配了 token，Composer 也会因预检失败而退出。
