RubyGems 国内安装失败？索引、Gem 下载与 Bundler 指南
RubyGems.org 网页搜索、Compact Index、Gem 文件下载和 Bundler 依赖解析是不同请求。大陆开发者可能 gem 页面能开，但 bundle install 卡在 Fetching；也可能文件已下载，原生扩展编译仍失败。
先用 gem sources 和一个纯 Ruby 小包测试索引与下载，再执行项目 bundle。不要把缺少编译器、系统库或 Ruby 版本不匹配归为网络问题。
网页、索引、Gem 文件与本地编译分开
网页能搜索
不代表 CLI 的 Compact Index、证书和代理配置正常。
Fetching 卡住
检查 Bundler source、DNS、TLS、代理和锁文件，不直接删除 Gemfile.lock。
下载后安装失败
原生扩展需要编译器、头文件与系统库，网络已不是主要原因。
版本解不出来
检查 Ruby、平台、依赖约束和 yanked 版本，不用换节点强行解决。
从小型 Gem 到项目 Bundle
- 1
检查 Ruby 与 Gem
记录 ruby、gem、bundler 版本和当前 source。
- 2
测试索引连接
查询一个常见 Gem 并查看详细版本，不先改全局配置。
- 3
安装纯 Ruby 小包
确认索引、Gem 文件和安装目录都正常。
- 4
执行 bundle check
先查看缺失依赖，再运行 bundle install 并保留错误日志。
- 5
处理原生扩展
按错误安装编译工具和系统开发库，核对 Ruby 架构。
不要随意删除 lock 文件
Gemfile.lock 保证团队版本一致。网络失败时应先检查 source 与缓存，避免无意升级整套依赖。
忍者云改善索引和文件下载，不编译扩展
忍者云可改善 RubyGems 网页、Compact Index 和 Gem 文件的跨境连接。Shell、IDE、容器和 CI 需分别配置，并用同一小包逐项验证。
企业项目还应区分公开 RubyGems 与私有 Gem Server。私有源 Token 不得写进 Gemfile 或日志，CI 中应使用受保护变量，并确认 source 顺序不会把内部包名解析到公开仓库，避免依赖混淆风险。
原生扩展失败时保留 mkmf.log、编译器输出、Ruby ABI 和完整平台信息；macOS、Linux、Windows 与不同 Ruby 实现需要的工具链可能完全不同，不能复制另一台机器的修复命令直接执行。
线路不能解决依赖冲突、Ruby ABI、编译器、系统库、权限或 yanked 版本，也不替代私有 Gem 凭据。构建失败应根据 extconf 与编译日志处理。
可改善
网页、Compact Index、Gem 文件和 Bundler 网络请求。
不能改变
Ruby 版本、依赖约束、原生编译、系统库、权限和私有凭据。
Ninja Cloud
先用纯 Ruby 小包验证索引与下载
忍者云帮助连接 RubyGems 与 Bundler；Ruby 版本、依赖解析和原生扩展编译仍需本地处理。
常见问题
RubyGems 网页能开，bundle 为什么卡住？
CLI 使用索引和文件端点，并有独立代理与 TLS 环境，应检查 Bundler 配置。
Gem 下载后 extconf 失败是网络问题吗？
通常不是。检查编译器、头文件、系统库和 Ruby 架构。
可以删除 Gemfile.lock 重试吗？
不要把它当作网络排查步骤，删除会重新解析并可能升级依赖。
忍者云能解决依赖冲突吗？
不能。依赖约束需调整 Gemfile、Ruby 或 Gem 版本。