使用x-oauth-basic认证安装GitHub私有Gem时bundle install失败怎么办？

问题根源 #

开启GitHub双重认证（2FA）后，原有的密码认证方式失效，必须使用**个人访问令牌（PAT）**进行私有仓库访问，同时原Gemfile的URL格式存在兼容性问题，导致Bundler无法完成认证。

具体解决步骤 #

1. 确认个人访问令牌（PAT）权限

生成PAT时必须勾选repo权限（用于访问私有仓库），若Gem所在仓库属于组织，还需确保令牌拥有该组织的访问权限。生成后务必妥善保存，令牌只会显示一次。

2. 修正Gemfile中的私有Gem配置格式

原配置中的:x-oauth-basic后缀已不再适用，需调整为正确的HTTPS认证格式：

# 修正后的HTTPS格式
gem 'my_gem', git: "https://#{ENV['PRIVATE_LIB_TOKEN']}@github.com/obromios/my_gem.git", branch: 'master'

# 或使用git_source简写方式（更简洁）
gem 'my_gem', github: 'obromios/my_gem', branch: 'master', auth_token: ENV['PRIVATE_LIB_TOKEN']

3. 验证环境变量加载有效性

• 本地开发时，确保.env文件被正确加载：若使用dotenv-rails，需在Gemfile中添加gem 'dotenv-rails', groups: [:development, :test]，Rails 5+会自动加载.env文件。
• 验证环境变量：在项目目录终端执行echo $PRIVATE_LIB_TOKEN，或在Rails控制台执行ENV['PRIVATE_LIB_TOKEN']，确认输出正确的令牌内容。

4. 彻底清理Bundler缓存

仅删除单个缓存文件夹无法彻底解决问题，需执行以下命令清理所有相关缓存：

bundle clean --force
rm -rf ~/.rvm/gems/ruby-2.7.4/cache/bundler/git/
rm -rf vendor/cache/

清理完成后重新执行bundle install。

5. Heroku部署配置

• 在Heroku上设置环境变量：

  heroku config:set PRIVATE_LIB_TOKEN=你的个人访问令牌
  

• 若Heroku使用的Bundler版本过旧，可升级Bundler：

  heroku run bundle update --bundler
  

6. 备选方案：改用SSH协议访问

若HTTPS方式仍存在问题，可切换为SSH协议：

1. 生成SSH密钥并添加到GitHub账户。
2. 修改Gemfile配置：

   gem 'my_gem', git: "git@github.com:obromios/my_gem.git", branch: 'master'
   

3. 测试SSH连接有效性：ssh -T git@github.com，确认能正常访问GitHub。

内容的提问来源于stack exchange，提问作者Obromios