私有包403错误本质是认证缺失，需检查GitHub Token域名匹配、GitLab/Satis仓库type与URL完整性、auth.json权限及CI环境Token注入。
私有包403错误本质是认证缺失，不是网络或镜像问题
报错含 403 Forbidden 且指向私有 Git 仓库（如 gitlab.example.com、github.com/private-org/private-lib）时，Composer 已成功连上服务器，但被明确拒绝访问——说明 DNS、TLS、路由都没问题，卡点只在身份校验环节。别去调 http-max-concurrent-downloads 或换镜像源，那对私有源完全无效。
GitHub 私有仓库 403：Token 配置必须严格匹配域名
GitHub 的 OAuth 认证只认 github.com 这个域名，写成 api.github.com、www.github.com 或带协议前缀都会静默失效：
-
composer config --global github-oauth.github.com ghp_xxx—— 正确（注意是github.com） -
composer config --global github-oauth.api.github.com ghp_xxx—— 无效，Composer 直接忽略 - 验证是否生效：
composer config --global github-oauth.github.com应输出掩码后的 Token（如ghp_***abc123），不是空行或null - Token 必须勾选
repo权限；复制时若带前后空格或换行，可用echo "$TOKEN" | hexdump -C检查不可见字符 -
~/.composer/auth.json文件权限必须是600（Linux/macOS），否则 Composer 跳过读取
GitLab / 自建 Satis 源 403：URL 和 type 必须完整，不能省略
Composer 对 repositories 配置极其敏感，漏一个字段就静默跳过整个区块，回退到默认源查包，结果必然是 404 或 403：
- GitLab 私库必须声明
"type": "vcs"，且 URL 是完整 Git 地址："url": "https://gitlab.example.com/group/project.git"（末尾.git不能少） - 若需 Basic Auth，不能把用户名密码塞进 URL（如
https://user:pass@gitlab.example.com/...），而应走auth.json配置：{"http-basic": {"gitlab.example.com": {"username": "xxx", "password": "yyy"}} - Satis 或 Private Packagist 类服务，
type必须是composer，且 URL 指向packages.json所在根路径，例如"url": "https://satis.example.com/"（末尾斜杠不能少，否则拼出/packages.json时路径错位） - 配置完立刻运行
composer config --list | grep repositories确认内容已写入，别只改composer.json就跑命令
403 卡在 “Resolving packages” 阶段：说明正在调 GitHub API，不是下载包本身
如果 composer install -vvv 卡在 Resolving packages 并最终报 403，日志里出现大量 api.github.com 请求，那问题不在私有包仓库，而在 Composer 正在解析依赖树中某个 dev-* 分支或 fork 项目——它需要 GitHub API 列出分支/Tag，而你没配 Token：
- 哪怕只装一个私有包，只要它的
composer.json里require了"monolog/monolog": "dev-main"，Composer 就会去api.github.com查 monolog 的分支列表 - 这个请求不走私有源配置，也不受
repositories影响，必须单独配github-oauth.github.com - CI 环境中尤其常见，因为
GITHUB_TOKEN环境变量不会自动注入到 Composer 的 auth.json，得显式执行composer config --global github-oauth.github.com $GITHUB_TOKEN
真正难排查的是“部分包能装、部分包 403”，这往往意味着多个私有源混用时，只有其中一个配了认证，或 auth.json 里某条域名写错了端口（比如 gitlab.example.com:8443 漏了 :8443）。每次改完配置，务必用 curl -v -u user:pass https://gitlab.example.com/api/v4/projects 或对应健康检查接口手动验证，别只信 Composer 的报错信息。
