composer config -g github-oauth.github.com是唯一有效写入方式，其他路径如改项目composer.json、手动编辑auth.json或用http-basic均无效；github api元数据请求发生在全局解析阶段，仅-g配置能覆盖全链路。
composer config -g github-oauth.github.com 是唯一有效写入方式
其他路径——改项目 composer.json、手动编辑 ~/.composer/auth.json、用 http-basic 配置——全都不起作用。GitHub API 的元数据请求（查 tag、读远程 composer.json、解析依赖树）发生在安装前的全局解析阶段，此时项目目录还没加载，auth.json 也未被读取。只有 composer config -g 写入的配置会提前注入整个链路。
常见错误包括：
- 漏掉
-g参数 → token 被写进当前项目的composer.json的config字段，换个项目就失效，还可能误提交到 Git - 把域名写成
api.github.com或www.github.com→ Composer 完全不认，静默跳过认证，报错却是模糊的Could not fetch或伪装成 404 的 401 - Windows PowerShell 中直接粘贴含
$的 token →$被 shell 解析为空，建议改用 CMD，或手动粘贴纯字符串
验证是否写入成功：运行 composer config -g github-oauth.github.com。输出应为一串星号（如 ***），长度合理（通常 40 位）。空输出或报错说明根本没写进去。
Token 必须是 classic 类型且含 repo 权限
fine-grained token 当前主流 Composer 版本支持不稳定，不能用于生产环境。必须用 GitHub 后台生成的 Personal access tokens (classic)，且权限至少勾选 repo —— 它覆盖 public_repo 和 private_repo，是读取任何 GitHub 仓库元数据的最低要求。
其他权限按需添加：
-
read:packages：仅当你从ghcr.io拉取 GitHub Packages 上的私有 Composer 包时才需要 -
delete:packages：仅当你需要删除包时才加，Composer 安装过程从不删包 -
admin:org、delete_repo等高危权限完全没必要，且增加账户风险
如果组织启用了 SSO，即使 token 权限正确，也得去 GitHub 的 Settings → Applications → Authorized OAuth Apps 页面手动 approve 该 token，否则仍 401。
CI 环境中必须用 COMPOSER_AUTH 环境变量
在 GitHub Actions、GitLab CI 等场景下，硬编码 token 到 auth.json 文件再挂载，极易泄露（日志、镜像层、调试输出）。正确做法是运行时注入 COMPOSER_AUTH 环境变量。
格式必须是合法 JSON 字符串：
{"github-oauth":{"github.com":"ghp_xxx"}}
注意：
- Shell 中双引号要转义：
export COMPOSER_AUTH="{\"github-oauth\":{\"github.com\":\"$GITHUB_TOKEN\"}}" - 该变量优先级高于
~/.composer/auth.json，但若项目根目录存在auth.json，Composer 会跳过环境变量 —— CI 中务必先清理或重命名它 - GitHub Actions 推荐写法：
COMPOSER_AUTH='{"github-oauth":{"github.com":"${{ secrets.GITHUB_TOKEN }}"}'
配完别忘了清缓存并检查锁文件
配置生效后，旧的失败响应可能已被缓存。执行 composer clear-cache 强制刷新。
更关键的是检查 composer.lock：如果之前因认证失败导致部分依赖没拉下来，lock 文件里可能残留未完成的条目。此时仅 composer install 不够，必须跑一次 composer update --locked 或干脆 rm composer.lock && composer install 重建依赖图。
最容易被忽略的是：token 配对了，但项目 composer.json 里 repositories 的 URL 如果用了 git@github.com: 这类 SSH 地址，Composer 仍可能绕过认证走 git 协议——确保私有包声明为 vcs 类型且 URL 是 HTTPS 格式，例如 "url": "https://github.com/your-org/private-package"。
