Composer 报 403 错误主因是 GitHub API 调用超限或未携带有效 OAuth Token，导致匿名请求被拒；需配置具备 repo 和 read:packages 权限的 Personal Access Token，并确保正确写入全局配置且无空格、代理干扰或用户权限错配。
为什么 Composer 会报 403 错误？
这不是你没权限装包，而是 Composer 在访问 GitHub（或某些私有源）时被拒绝了——本质是 GitHub API 的调用限额超了，或者根本没带身份凭证。默认情况下，Composer 每小时只能匿名访问 GitHub API 60 次；一旦项目依赖多、更新频繁，或者用了 dev-master 这类需要实时查 Git 分支的版本，立刻就触发 403。
常见现象包括：Failed to download vendor/package from dist: HTTP/2 403、Could not fetch https://api.github.com/...、甚至 invalid credentials（哪怕你根本没配认证）。
- 403 多发生在
composer update或create-project阶段，尤其在 CI 环境或公司内网更明显 - 不是所有 403 都来自 GitHub：如果你配置了私有仓库但 token 过期、域名写错（比如
github.com写成www.github.com），也会返回 403 - 注意区分：403 ≠ 401。401 是凭证无效，403 是“你有凭证但没权限”，而实际中 Composer 报 403 往往是因为压根没传凭证 → 它自动降级为匿名请求了
怎么配 GitHub OAuth Token 才真正生效？
必须用 Personal Access Token（PAT），且权限要够，命令要写对。很多人卡在第三步：以为执行了命令就完事，其实 Token 没进对位置，或者被项目级配置覆盖了。
- 生成 Token 时，至少勾选
repo和read:packages；不用delete_repo或admin:org这类高危权限 - 配置命令必须是：
composer config --global github-oauth.github.com YOUR_TOKEN（注意是github.com，不是api.github.com或带https://） - 执行后检查是否写入成功：
composer config --global --list | grep github-oauth，应看到类似"github-oauth": {"github.com": "ghp_..."} - 如果项目根目录下有
composer.json里写了repositories，且其中某条指向 GitHub，那它可能绕过全局配置——此时需确认该仓库是否也要求认证（比如私有组织 repo）
哪些情况会让 Token “看起来生效”实则失效？
Token 配了，composer update 还是 403？大概率掉进了这几个坑：
- Token 被复制时带了空格或换行（尤其是从网页复制到终端）→ 用
echo "$TOKEN" | hexdump -C看有没有0a（换行）或20（空格） - 公司网络或代理强制重写 Host 请求头，导致 GitHub 认不出
github.com域名 → 临时加--verbose看实际请求 URL 是否被篡改 - CI 环境（如 GitHub Actions）里硬编码了 Token，但没设为 secret，被日志打印出来 → 不仅失效还泄露风险，应改用
${{ secrets.GITHUB_TOKEN }}注入 - PHP 运行用户和配置用户不一致：比如用
sudo composer配的全局 Token 存在 root 用户家目录，但实际运行的是 www-data → 改用composer config --auth写入当前用户配置，或直接指定--no-interaction避免权限混用
除了配 Token，还有哪些关键动作能降低 403 概率？
Token 是核心，但光靠它不够。GitHub API 限流是按 IP + 凭证组合计数的，本地开发机多个项目共用一个 Token，照样可能撞限。
- 强制走 dist 包而非 source：
composer install --prefer-dist，避免触发git clone类请求（这类请求全走 GitHub API） - 关掉不必要的插件：有些插件（如
hirak/prestissimo）会并发拉取，加剧 API 压力 →composer global remove hirak/prestissimo - CI 中启用缓存：
cache: $HOME/.composer/cache（GitHub Actions），否则每次都是全新请求，Token 再稳也扛不住高频调用 - 别用
dev-*分支别名：比如"monolog/monolog": "dev-main"，它每次都要查最新 commit → 改用具体 commit hash 或稳定 tag
最常被忽略的一点：403 可能根本不是 GitHub 的问题——比如你用了已停用的镜像源（如 packagist.phpcomposer.com），它返回 403 并伪装成 GitHub 错误。先跑一遍 composer config -g repo.packagist，确认源地址没写死一个早就失效的域名。
