如何解决 Composer 在 macOS 上因 keychain 权限导致的认证失败？

composer在macOS因keychain权限拒绝导致git认证失败，需检查钥匙串凭据权限、配置git credential.helper为osxkeychain、避免Composer回退https，并重置Git凭据触发重新授权。

Composer 在 macOS 上因 keychain 权限拒绝访问凭据，会导致 git clone 或私有包安装时认证失败（如 401 Unauthorized 或 Permission denied (publickey)），根本原因是 Git 尝试从系统 keychain 读取凭证时被 macos 安全策略拦截。

检查并修复 keychain 中的 Git 凭据条目

macOS 的钥匙串可能存有损坏、过期或权限受限的 Git 凭据（如 github.com、gitlab.com 等）。打开“钥匙串访问”应用，搜索 github.com 或对应 Git 域名，找到类型为 internet password 的条目。双击打开，点击“访问控制”，确认“允许所有应用程序访问此项目”已勾选；若未勾选，勾选后点击“好”保存。也可直接删除旧条目，让 Git 下次自动重新存储（需配合正确的凭据配置）。

确保 Git 使用 osxkeychain 正确辅助工具

运行以下命令确认 Git 已启用 keychain 辅助：

git config --global credential.helper

应输出 osxkeychain。若为空或错误，执行：

微软爱写作

微软出品的免费英文写作/辅助/批改/评分工具

130

查看详情

• git config --global credential.helper osxkeychain
• 如果使用 apple Silicon Mac 且 Homebrew 安装了 Git，可能需用 git config --global credential.helper /opt/homebrew/bin/git-credential-osxkeychain（路径以 which git-credential-osxkeychain 输出为准）

避免 Composer 绕过 Git 凭据（禁用 https 回退）

Composer 默认在 ssh 失败时自动回退到 HTTPS，而 HTTPS 依赖 keychain 存储的用户名/密码。若你本意是走 SSH（如私有 GitLab 仓库），却因 keychain 拒绝导致 HTTPS 认证失败，可强制 Composer 仅用 SSH：

• 在 composer.json 中为仓库指定 "type": "vcs" 并确保 URL 是 git@... 格式（非 https://...）
• 运行 composer config --global github-oauth.github.com <your_token></your_token>（仅适用于 GitHub）或改用 SSH 密钥认证
• 临时禁用 HTTPS 回退：设置环境变量 export COMPOSER_DISABLE_HTTPS=1（不推荐长期使用）

重置 Git 凭据并触发重新授权

清除当前缓存的凭据，让 Git 重新弹出授权窗口（注意：需确保钥匙串权限已按第一点设好）：

• git credential reject，然后输入：
• protocol=https
• host=github.com
• username=（留空后回车）
• 之后执行任意需要认证的 Git 操作（如 git ls-remote git@github.com:vendor/package.git），macOS 会再次提示授权

基本上就这些。关键是钥匙串权限放开 + Git 辅助工具配置正确 + Composer 不意外降级到 HTTPS。不复杂但容易忽略权限细节。