为什么你的Composer OAuth配置总报401？四个隐蔽陷阱与修复指南
遇到Composer提示无效的OAuth令牌，反复重试却依然卡在401错误？这事儿确实让人头疼。但先别急着重新生成Token——很多时候，问题并不在令牌本身，而是配置环节的几个关键细节被忽略了。下面咱们就来逐一拆解这些隐蔽的陷阱。
为什么composer config --global github-oauth.github.com不生效
核心原因往往就出在漏了一个简单的标志上：--auth。如果少了它，Composer只会把Token当作一个普通的配置项，随手存进config.json文件里。结果呢？发起请求时，请求头里压根不会带上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这样的一行键值对，而不是一个嵌套在config对象里的结构。 - 如果已经配错：先用
composer config --global --unset github-oauth.github.com清理掉错误配置，再按照正确命令重配一次。
auth.json权限和路径不对导致静默失效
这可能是最让人困惑的情况之一：明明文件存在，配置也写了，可Composer就是“看不见”。其实，Composer对auth.json文件有两条严格的读取规则：文件必须存在且权限为600；文件路径必须在Composer的查找链上。只要有一条不满足，Composer就会直接跳过这个文件，而且通常连个警告都不会给。
常见的坑点包括：
- 文件权限不对：如果权限是
644或755，用chmod 600 auth.json命令修正它。 - 放错了地方：把
auth.json放在项目子目录（比如./config/）是无效的。它必须位于项目根目录，或者全局目录~/.composer/下。 - 被IDE或.gitignore误导：有时文件被
.gitignore忽略后可能被误删。别只相信IDE的文件树，用ls -l auth.json命令确认文件真实存在。 - 平台配置键名混淆：给GitLab配置要用
gitlab-token这个键，而不是http-basic；Bitbucket则必须使用password字段来配置App Password。
Token权限不足等于没配
令牌本身是有效的，但赋予的权限不够，结果还是一样。比如在GitHub上，如果只勾选了public_repo，那么访问私有仓库时就会碰壁——你需要的是repo权限。想拉取Packages？那还得加上read:packages。类似地，GitLab的Token如果只有read_repository而缺少read_api，同样会导致元数据拉取失败。
如何检查？可以这么做：
- GitHub：直接到Token管理页面点击
Edit，仔细核对已勾选的权限范围。 - GitLab：创建Token的页面会明确列出所有scope，不能只看Token是否处于“Active”状态。
- Bitbucket：在App Password管理页面右侧，会清晰展示已启用的权限列表。记住，创建时没勾选的权限，之后是不会自动生效的。
- 手动测试：一个很实用的方法是，用curl命令直接测试：
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user/repos?per_page=1，看看能否正常返回数据。
缓存没清干净，新凭证白配
这是另一个高频“杀手”。Composer的缓存分为两层：元数据缓存（来自repo.packagist.org等源的响应）和包文件缓存（下载的.zip等）。要命的是，401错误信息也可能被缓存在元数据层。这意味着，即使你后来更新了正确的Token，Composer可能还在固执地使用旧的、带错误信息的缓存流程。
因此，在修正配置后，务必执行清理：
- 运行
composer clear-cache来清除全部缓存。 - 如果问题依旧，补充执行
composer diagnose进行诊断，重点查看cache-dir路径是否可写，以及auth.json是否被正确识别。 - 在CI/CD环境中要特别注意：通过环境变量注入的Token，必须确保变量名拼写完全一致（例如
GITHUB_TOKEN和GITHUB_OAUTH_TOKEN就是两个不同的变量），并且没有被shell脚本意外截断或转义。
最后记住一个原则：Token本身通常不会“自动过期”。只要遇到401，第一反应不应该是急着重新生成Token，而是系统地确认以下链条：Token是否真的被Composer获取到了？是否被正确地放入请求头发出去了？目标平台是否认可这个Token的权限？按照这个思路排查，绝大多数认证问题都能迎刃而解。
