composer 配置 github token 必须用 composer config -g github-oauth.github.com ，域名只能是 github.com，-g 不可省略；token 需含 repo 权限，ci 中应通过 composer_auth 注入，优先级顺序为项目 auth.json > composer.json > 全局配置。
composer config -g github-oauth.github.com 写不对就白配
这条命令是配置 GitHub Token 的核心入口，但错一个字符、少一个参数或写错域名都会让认证完全失效。最常见的是把 github.com 误写成 api.github.com 或 www.github.com，Composer 只认 github.com 这个 host 名。
必须加 -g（global），否则会写进当前项目的 composer.json，极容易误提交到 Git —— 尤其是团队项目里，这等于把 token 暴露在公开仓库中。
执行时注意：
- Windows 用户在 PowerShell 中，
$符号需转义，建议改用 CMD；或者直接用composer config -g github-oauth.github.com ghp_xxx手动粘贴 - token 字符串前后不能有空格或换行，复制时容易带入 invisible character，验证方式是运行
composer config -g github-oauth.github.com—— 如果只输出几个星号（如***）且长度合理（通常 40 位），说明存进去了；如果输出空或报错，大概率是写入失败或格式异常 - 别手动编辑
~/.composer/auth.json，Composer 不校验 JSON 格式，手写错一个逗号就会导致后续所有请求静默失败
Token 权限不够会导致 401 而不是限流提示
遇到 Could not authenticate against github.com 或 Failed to download，第一反应不该是“token 过期”，而应检查权限是否足够。GitHub 已停用密码和 OAuth App 认证，现在只接受 Personal Access Token（PAT），且必须勾选 repo —— 即使只拉私有库的 composer.json，也依赖该权限读取仓库元数据。
其他常见权限误区：
-
read:packages：仅当你使用 GitHub Packages（比如私有 Composer 包托管在 ghcr.io）时才需要 -
delete:packages、admin:org等高危权限完全没必要，Composer 从不 push、delete 或管理组织设置 - 如果组织启用了 SSO，即使 token 权限正确，也得先去 GitHub 的
Settings → Applications → Authorized OAuth Apps页面手动 approve 该 token
CI 环境（如 GitHub Actions）不能硬编码 token
GitHub Actions 默认提供 ${{ secrets.GITHUB_TOKEN }}，但直接塞进 composer config -g 会失败 —— 因为 composer config 存的是字符串字面量，不会做环境变量展开。
正确做法分两步：
- 在 workflow 文件中通过
COMPOSER_AUTH环境变量注入（推荐，兼容所有 Composer 版本）：COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GITHUB_TOKEN }}"}' - 或在项目级配置中写
"github.com": "${GITHUB_TOKEN}"（Composer 2.2+ 支持），再确保 CI 环境已设好GITHUB_TOKEN环境变量 - 绝对不要在
.yml里用composer config -g github-oauth.github.com ${{ secrets.GITHUB_TOKEN }}—— 这会把未展开的字符串写进全局配置，且泄露风险极高
配置生效但拉私有库仍失败？优先查 auth.json 优先级
Composer 查找认证信息的顺序是：当前目录下的 auth.json > 项目 composer.json 中的 config.github-oauth > 全局 ~/.composer/auth.json。哪怕你全局配好了，只要项目根目录存在 auth.json，它就会被优先读取 —— 而这个文件可能残留旧 token、格式错误，甚至为空。
排查建议：
- 运行
composer config --list和composer config -g --list对比，确认实际生效的是哪一层 - 临时重命名项目下的
auth.json，再试composer update，看是否恢复正常 - 企业版 GitHub（GHES）用户注意：
github.com的 token 对github.company.internal无效，得单独运行composer config -g github-oauth.github.company.internal <token></token>
真正麻烦的从来不是生成 token，而是 Composer 在多层配置间静默选择某一个，还不会报错提醒你它到底用了哪个。
