github-domains仅作域名白名单校验,不处理认证与通信;必须同步配置auth.json的PAT token、确认API路径支持/api/v3、运行composer clear-cache清缓存,三者缺一不可。

直接配 github-domains 不生效,是因为它只是白名单开关,不是通信配置——必须同步配 auth.json 的 token、确认 API 路径、清缓存,三者缺一不可。
github-domains 只校验 Host,不处理认证
github-domains 的作用非常窄:它只告诉 Composer “哪些域名允许走 GitHub 协议解析”,比如 "git.example.com"。它不负责登录、不传 token、不改 API 地址。
- 值必须是字符串数组,写成
"https://git.example.com"或带路径如"git.example.com/github"都会失效 - 如果企业版部署在子路径(如
https://git.example.com/github),仍只填"git.example.com" - 配完必须运行
composer clear-cache,否则旧缓存里的域名列表不会更新——这步没提示,但跳过就永远连不上
auth.json 必须为每个域名单独配 token
GitHub Enterprise 不认全局 OAuth token,必须在 auth.json 里按域名映射 Personal Access Token(PAT)。
- token 类型必须是 Personal Access Token,不能是 OAuth App Token
- 权限至少勾选
repo(读私有库)和read:packages(如果用 GitHub Packages) - 若启用了 SSO,生成 token 时要点 “Enable SSO” 按钮,否则返回
401 Unauthorized - 示例内容(放在项目根目录或
~/.composer/auth.json):{"github-oauth": {"git.example.com": "ghp_abc123..."}}
私有包 require 必须显式声明 VCS 仓库
Composer 不会把 "vendor/package": "dev-main" 自动映射到你的 GitHub Enterprise 实例——它默认只查 github.com。
- 必须在
composer.json的repositories中加一条"type": "vcs",URL 用完整 HTTPS 地址:{"type": "vcs", "url": "https://git.example.com/owner/repo.git"} - 不能只靠
github-domains+require就想拉取,那样会去github.com找,报Could not find package - 如果用 GitHub Packages(
npm.pkg.github.com类似物),需额外配"type": "package"和"options": {"auth": {...}}
API 路径和版本兼容性容易被忽略
GitHub Enterprise 默认 API 根路径不是 /api/v3,而是取决于部署版本:2.x 用 /api/v3,3.x+ 默认用 /api/v4(GraphQL)。Composer 内部调用的是 REST API,所以必须确保实例支持 /api/v3 且可访问。
- 手动测试:用 curl 访问
https://git.example.com/api/v3/meta,应返回 JSON 且 HTTP 状态码为 200 - 如果返回 404,说明实例禁用了 v3 API,或反向代理拦截了
/api/v3路径 - 某些旧版 GHE(如 2.22 之前)不支持
read:packages权限,token 即使正确也会在拉 Package 时失败











