Ruby项目安装依赖时，gem install成功并不代表bundle install一定成功。Bundler会解析Gemfile与锁文件，访问一个或多个Gem源，还可能拉取Git依赖。Ruby版本、OpenSSL、Bundler版本和运行账号不同，也会让同一台机器表现不一致。
一、安装链路先拆成三段
| 组件 | 负责内容 | 重点检查 |
|---|---|---|
| RubyGems | Gem源、元数据和包安装 | 源地址、代理、CA与Ruby版本 |
| Bundler | 解析Gemfile与锁文件 | 配置层级、多个源和缓存 |
| Git | 获取Git形式依赖 | HTTPS/SSH代理与仓库权限 |
二、先确认实际使用的Ruby环境
使用系统Ruby、rbenv、RVM、容器或CI工具链时，ruby、gem和bundle可能来自不同路径。先记录版本与可执行文件位置，再检查OpenSSL和CA。不要只看终端提示中的Ruby版本名称。
三、代理配置应放在哪一层
RubyGems与Bundler可受常见代理环境变量和自身配置影响，具体键及优先级应按当前版本核对。临时排障可在单次Shell中注入，长期使用则应选择权限受限的用户或CI配置。项目仓库不应保存真实代理密码。
四、Gem源和代理不是同一个问题
Gem源决定依赖从哪里获取，代理决定如何访问它。切换到其他镜像会改变供应链来源、同步速度和信任责任；设置代理不会改变包源。应先确认团队认可的源，再排查网络，不要为了绕开证书错误改用未知HTTP镜像。
五、Bundler为何会访问多个域名
源站元数据、Gem文件、GitHub或其他代码托管的Git依赖可能使用不同主机。错误日志中的实际URL比Gemfile首页更重要。若存在重定向，还需检查最终下载主机是否符合代理和证书策略。
六、Git依赖怎么单独检查
Gemfile中的Git依赖会进入Git网络链路。HTTPS远程可受Git HTTP代理影响，SSH远程则使用SSH配置。Bundler本身能够访问Gem源，不代表Git仓库可达。
相关方法见Git代理、远程协议与凭据安全。
七、407、401和Gem找不到版本如何区分
- 407：代理认证失败或认证机制不兼容；
- 401/403：私有Gem源或Git仓库权限；
- 找不到版本：检查源同步、平台、Ruby版本和锁文件；
- 连接超时：确认DNS、代理、目标主机和下载阶段；
- SSL错误：检查CA、时间和证书链。
八、证书错误为什么常跟Ruby版本有关
不同Ruby安装可能链接不同OpenSSL并使用不同CA路径。浏览器和系统curl正常，不代表当前Ruby信任相同根证书。应检查实际解释器及其证书环境，更新受控CA或工具链，而不是关闭SSL校验。
TLS排查顺序见HTTPS代理证书错误指南。
九、凭据怎样避免泄露
代理密码、私有Gem源令牌和代码仓库凭据属于三类秘密。避免将它们写入Gemfile、锁文件、镜像层或CI输出。使用受保护的秘密变量，限制环境和分支范围，并检查Bundler诊断信息是否包含带认证的源URL。
十、缓存为什么会造成环境差异
开发机可能已缓存Gem，CI新节点则必须下载。验证网络时应从日志确认缓存命中与真实请求，不要用一次本地成功推断CI出口正常。共享缓存需要只允许可信任务写入，并结合锁文件与校验。
十一、排查清单
- 记录Ruby、RubyGems、Bundler和Git版本；
- 确认依赖来自Gem源还是Git；
- 检查执行进程代理及Bundler配置来源；
- 区分407、源认证、TLS与版本解析；
- 核对最终包文件和Git主机；
- 在实际CI用户或容器中复测；
- 清理临时认证信息和调试日志。
十二、结论
RubyGems和Bundler代理问题的关键，是分开看Gem源、包文件和Git依赖。明确Ruby运行环境与配置来源后，再处理认证和证书，才能避免“本机有缓存、CI却失败”的反复问题。
