【Git】 工具报错 "HTTP Basic: Access denied" 的排查与终极解决方案

最近在使用某 Git GUI 工具（如 HBuilderX、ugit 等）管理私有 GitLab 仓库时，遇到一个非常顽固的问题：

[10:39:52] 开始: git -c credential.helper= fetch ...
remote: HTTP Basic: Access denied
fatal: Authentication failed for 'http://gitlab.example.com/username/project.git/'

诡异的是，同一个账号下的其他仓库都能正常拉取，而且直接在终端（Terminal）里手动 git clone/pull 也是正常的。唯独这一个仓库，无论怎么输账号密码，甚至用了 Token，工具死活报错认证失败。

问题分析

仔细观察报错日志，发现工具在执行命令时带了一个特殊的参数： -c credential.helper=

这个参数的意思是：强行清空/禁用 Git 的凭据助手。

• 这意味着该工具决定“自己接管”认证过程，不让 Git 去查系统（如 macOS Keychain 或 Windows 凭据管理器）里存的密码。
• 既然终端能跑通，说明系统里的账号密码（或 Token）是对的。
• 工具报错，说明工具自己针对这个特定项目缓存了错误的凭据，或者传递凭据的方式被 GitLab 的安全策略（如 2FA 或 HTTP 限制）拒绝了。

排查：如何查看本地已保存的密码？

在 macOS 上，Git 默认将密码保存在“钥匙串”中。如果你想确认系统里到底存了什么账号和密码（或者确认是否存进去了），可以使用 git credential-osxkeychain get 命令来查看。

printf "protocol=http\nhost=gitlab.example.com\n" | git credential-osxkeychain get

如果钥匙串里有记录，它会输出类似下面的内容：

protocol=http
host=gitlab.example.com
username=myusername
password=glpat-xxxxxxxxxxxx

如果什么都没输出，说明系统里没有存这个域名的密码。

解决方案

既然工具“顽固”地不肯用对的密码，我们可以用一种“降维打击”的方式：直接把 Token 嵌入到远程仓库的 URL 里。这样 Git 在连接时会直接读取 URL 里的身份信息，完全绕过任何凭据助手的干扰。

步骤一：生成 Access Token (如果还没有)

不要用登录密码，去 GitLab/GitHub 生成一个 Personal Access Token。

步骤二：修改项目的远程 URL

打开终端，进入该项目的根目录，执行以下命令：

# 进入项目目录
cd /path/to/your/project

# 格式：git remote set-url origin http://用户名:Token@域名/仓库路径.git
git remote set-url origin http://myusername:glpat-xxxxxxxxxxxx@gitlab.example.com/group/project.git

注意替换：

• myusername: 你的 Git 用户名
• glpat-xxxxxxxxxxxx: 你的 Access Token
• 后面的地址保持和你原来的一样。

步骤三：验证

回到你的 GUI 工具里，再次点击“拉取”或“同步”。这时候应该就能成功了！因为认证信息直接包含在请求地址里，工具再怎么禁用凭据助手也没用了。

⚠️ 安全提示： 这种方法会将 Token 明文保存在本地项目的 .git/config 文件中。虽然只是保存在本地，但如果此时有人能物理接触你的电脑查看该文件，可能会泄漏 Token。建议该 Token 仅授予当前项目必要的权限，并定期轮换。