加-g将token写入全局auth.json，确保所有GitHub API调用（含Packagist元数据解析）均认证通过；不加-g仅写入项目composer.json但无效，因依赖解析阶段不加载项目级配置。
为什么composer config -g github-oauth.github.com必须加-g
不加-g会把 token 写进当前项目的composer.json的config字段里，而 Composer 在解析依赖元数据（比如查 packagist.org 上某个包对应 GitHub 仓库的 latest tag）时，根本不会加载项目级配置——它走的是全局认证链路。此时即使项目里写了 token，API 请求照样以匿名身份发出，一小时 60 次限额立刻见底。
加-g才写入~/.composer/auth.json，这个文件在 Composer 启动初期就被读取，覆盖整个安装/更新流程，包括 Packagist 元数据抓取、递归依赖解析、私有 repo 地址发现等所有 GitHub API 调用环节。
-
composer config github-oauth.github.com xxx→ 错，只影响当前项目，且不生效于关键阶段 -
composer config -g github-oauth.github.com xxx→ 对，全局生效 -
composer config --global github-oauth.github.com xxx→ 等价于-g，但别拼错--global成--gloabal这类 typo
github-oauth.github.com权限到底要勾哪些
只勾public_repo看似够用，但实际多数失败都卡在这儿：Composer 拉取 fork 的包、解析子模块、甚至某些 public 包的composer.json里嵌了repositories指向私有源，都会触发repo scope 校验。报错常是403 Forbidden或404 Not Found，而非明确提示权限不足。
必须勾选：repo（全选其下子项，含repo:status、repo_deployment等）、read:packages（若用 GitHub Packages）。不需要delete:packages或admin:org这类高危权限。
- classic token 已逐步弃用，优先用 fine-grained token，限制资源范围为
github.com和具体仓库 - token 名建议带用途，如
composer-global-2026，方便后续在 GitHub Settings 里快速定位回收 - 生成后页面关闭就再也看不到明文，复制时注意别带前后空格或换行符
CI 环境里千万别写死 token 到auth.json
GitHub Actions、GitLab CI 这类环境里，直接运行composer config -g会把 token 明文落盘到~/.composer/auth.json，一旦日志开启 debug 或 runner 配置不当，token 就可能泄露。更安全的做法是跳过文件写入，改用COMPOSER_AUTH环境变量。
正确写法（以 GitHub Actions 为例）：
COMPOSER_AUTH='{"github-oauth":{"github.com":"'"${{ secrets.GITHUB_TOKEN }}"'}}' composer install注意单双引号嵌套：外层单引号防止 shell 展开，中间"${{ secrets.GITHUB_TOKEN }}"由 Actions 自动注入并转义。
- GitLab CI 可设
GITHUB_TOKEN变量，再用COMPOSER_AUTH='{"github-oauth":{"github.com":"'$GITHUB_TOKEN'"}}' composer install -
COMPOSER_AUTH优先级高于auth.json，无需清理旧文件 - 别在
.gitignore里删掉auth.json——它默认就在里面，手抖删了反而让本地调试失效
auth.json权限不对也会导致认证失败
就算 token 正确、-g没漏、权限也勾全了，如果~/.composer/auth.json属主不是当前运行composer的用户，或者权限大于600，Composer 会直接拒绝读取，并抛出Could not authenticate against github.com——连 token 对不对都来不及验证。
修复命令：
chown $USER:$USER ~/.composer/auth.json<br>chmod 600 ~/.composer/auth.json
常见诱因：用sudo composer首次配置，导致文件属主变成root；或手动cp别人家的auth.json过来，忘了改权限。
- 运行
ls -l ~/.composer/auth.json确认输出类似-rw------- 1 youruser youruser - 如果项目里同时存在
composer.json里的config.github-oauth和全局auth.json，前者优先级更高，容易掩盖真实问题
真正卡住人的从来不是“怎么配”，而是“配了但不生效”——往往因为权限、作用域、环境变量展开方式这些细节没对齐。尤其在 CI 里，token 不是贴进去就完事，得让它在进程启动那一刻就进入 Composer 的认证上下文，而不是躺在文件里等被忽略。
