Elasticsearch Ruby 客户端安装与版本兼容指南

安装（Installation）

方式一：直接安装最新版本（Rubygems）

gem install elasticsearch

方式二：在 Bundler/Gemfile 中声明

# Gemfile
gem 'elasticsearch'

然后执行：

bundle install

指定安装某个主版本/具体版本

• 指定确切版本：

gem install elasticsearch -v 7.0.0

• 在 Gemfile 中约束主版本（例如 7.x）：

# Gemfile
gem 'elasticsearch', '~> 7.0'

提示：~> 7.0 会允许 7.0 到 7.x 的更新，但不会升级到 8.x。

版本兼容（Elasticsearch ↔ Ruby 客户端）

• Ruby 版本支持 ：客户端仅支持当前仍在维护的 Ruby 版本，遵循 Ruby 官方维护策略（Maintenance Branches）。
• 前向兼容 （Forward compatible）：语言客户端与 更高或相同的次版本 的 Elasticsearch 通信通常不破坏（例如：8.12 客户端可连 8.13 服务器），但不代表自动支持新特性；若要使用新特性，需要升级到相应版本的客户端。
• 向后兼容 ：仅对 默认发行版 提供有限的向后兼容，不作保证。

快速对照表

Gem 版本	可连接的 Elasticsearch 版本	说明
7.x	7.x（建议到 7.17）	7.x 客户端用于 7.x 服务器
8.x	8.x	8.x 客户端用于 8.x 服务器
main	main	面向主分支的开发版本

实战建议：服务器与客户端保持同一主版本（7 对 7、8 对 8），并尽量在小版本上保持同步，以获得最新 API 支持与修复。

小结

• 生产环境推荐在 Gemfile 中锁定主版本，并按需升级到对应小版本以获取新特性/修复。
• 需要使用新版本 Elasticsearch 的新能力时，客户端也要同步升级到该能力对应的版本。
• 请确保使用仍在维护的 Ruby 版本，避免因为运行时 EOL 造成支持问题。