Windows系统Ruby环境下mysql2客户端库版本不匹配问题求助

核心原因 #

mysql2 gem编译时依赖的MySQL客户端库版本（10.8.8是MariaDB的版本号，MariaDB为MySQL分支）和系统当前加载的客户端库版本（3.3.8）不一致，触发版本校验失败。

解决步骤 #

1. 确认系统中数据库客户端版本 #

打开命令提示符，执行：
mysql --version
查看输出的版本：如果是MariaDB，版本号为10.x开头；如果是MySQL，版本为8.x或5.x。3.3.8大概率是系统中存在旧版MySQL客户端（如MySQL Connector/C）或PATH路径中存在冲突的库文件。

2. 彻底卸载现有mysql2 gem #

执行：
gem uninstall mysql2
选择卸载所有版本，确保清理干净。

3. 指定正确客户端库路径重新编译mysql2 gem #

场景A：使用MariaDB（版本10.x）

找到MariaDB安装目录（如C:\Program Files\MariaDB 10.8），执行：
gem install mysql2 -v '0.5.5' --platform=ruby -- '--with-mysql-dir="C:\Program Files\MariaDB 10.8" --with-mysql-lib="C:\Program Files\MariaDB 10.8\lib" --with-mysql-include="C:\Program Files\MariaDB 10.8\include"'

场景B：使用MySQL（如8.x版本）

找到MySQL安装目录（如C:\Program Files\MySQL\MySQL Server 8.0），执行：
gem install mysql2 -v '0.5.5' --platform=ruby -- '--with-mysql-dir="C:\Program Files\MySQL\MySQL Server 8.0" --with-mysql-lib="C:\Program Files\MySQL\MySQL Server 8.0\lib" --with-mysql-include="C:\Program Files\MySQL\MySQL Server 8.0\include"'

4. 调整PATH环境变量优先级 #

确保数据库的bin目录在PATH最前端，避免旧版库被优先加载：

• 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
• 在系统变量的PATH中，将C:\Program Files\MariaDB 10.8\bin（或对应MySQL的bin目录）移至最顶部
• 重启命令提示符，使PATH生效

5. 验证安装效果 #

进入Rails项目目录，执行：
bundle install
随后尝试运行rails console，检查是否仍报错。

补充方案（若上述步骤无效） #

• 卸载系统中多余的MySQL/MariaDB版本，避免版本冲突
• 下载与数据库版本匹配的MySQL Connector/C，编译时指定其路径：
  gem install mysql2 -v '0.5.5' --platform=ruby -- '--with-mysql-dir="C:\mysql-connector-c-8.0.33-win64" --with-mysql-lib="C:\mysql-connector-c-8.0.33-win64\lib" --with-mysql-include="C:\mysql-connector-c-8.0.33-win64\include"'

内容的提问来源于stack exchange，提问作者Jérôme BORGA