必须加--auth标志，否则Composer将token存为普通配置而非认证凭据，导致请求头缺失Authorization字段而返回401；正确命令为composer config --global --auth github-oauth.github.com YOUR_TOKEN。
为什么composer config --global github-oauth.github.com不生效
因为漏了--auth标志。Composer 把 token 当成普通配置项存进config.json，但不会把它注入请求头。结果就是每次发请求时 Header 里没有Authorization: Bearer xxx，GitHub 直接返回 401。
正确做法是：
- 必须加
--auth：运行composer config --global --auth github-oauth.github.com YOUR_TOKEN - 验证是否写对位置：执行
composer config --global --list | grep github-oauth，输出应为github-oauth.github.com : xxx（不是github-oauth嵌套在config里） - 如果已错配，先删掉：
composer config --global --unset github-oauth.github.com，再重配
auth.json权限和路径不对导致静默失效
Composer 只读auth.json当它满足两个条件：文件存在且权限是600；路径在查找链上。否则直接跳过，连警告都不报。
常见问题：
- 权限是
644或755→ 运行chmod 600 auth.json - 放在项目子目录（如
./config/auth.json）→ 必须移到项目根目录，或~/.composer/auth.json - 被
.gitignore屏蔽后误删 → 检查ls -l auth.json是否存在，别只信 IDE 文件树 - GitLab 配置要写
gitlab-token键，不是http-basic；Bitbucket 必须用password字段配 App Password
Token 权限不足等于没配
GitHub 上只勾public_repo不够——私有库要repo，访问 Packages 要read:packages；GitLab 的read_repository缺了read_api会导致元数据拉不到；Bitbucket 的 App Password 必须开Repositories: Read。
检查方式：
- GitHub：点 Token 页面的
Edit，确认勾选状态 - GitLab：Token 创建页明确列出 scope，不能只看“Active”状态
- Bitbucket：App Password 页面右侧显示已启用权限，不是创建时勾的就永远有效
- 用
curl -H "Authorization: Bearer xxx" https://api.github.com/user/repos?per_page=1手动测 token 是否可用
缓存没清干净，新凭证白配
Composer 缓存包含两层：元数据（repo.packagist.org响应）和包文件（.zip）。401 错误常被缓存在元数据层，即使 token 更新了，Composer 仍按旧缓存走流程。
务必执行：
-
composer clear-cache（清除全部） - 如果还报错，补一句
composer diagnose，重点看cache-dir路径是否可写、auth.json是否被识别 - CI 环境中注意：环境变量注入的 token 要确保变量名拼写一致（如
GITHUB_TOKEN≠GITHUB_OAUTH_TOKEN），且未被 shell 转义截断
Token 本身不会“自动过期”，但平台侧可能轮换密钥或吊销权限。只要报 401，第一反应不该是重生成 token，而是确认它是否真被 Composer 拿到、送出去、被对方认出来。
