如何修复Ruby on Rails项目bundle install时mysql2安装失败的错误

问题本质 #

Windows环境用Ruby 3.0执行bundle install安装mysql2（0.5.6）失败，核心原因是缺少MySQL的C开发头文件和库文件，导致编译原生扩展时出错，具体报错是mkmf.rb中调用split方法时遇到nil值。

解决步骤 #

1. 安装MySQL开发组件 #

mysql2的原生扩展依赖MySQL的开发库，必须先完成这一步：

• 下载并安装MySQL Installer，选择包含「Developer Components」的版本；或者单独安装MySQL Connector/C
• 记好安装路径，比如默认的C:\Program Files\MySQL\MySQL Server 8.0或者C:\Program Files\MySQL\Connector C 6.1

2. 手动指定路径安装mysql2 gem #

打开命令提示符（建议用管理员模式），把下面的路径换成你的实际安装路径，执行命令：

gem install mysql2 -v 0.5.6 -- --with-mysql-dir="C:\Program Files\MySQL\MySQL Server 8.0" --with-mysql-lib="C:\Program Files\MySQL\MySQL Server 8.0\lib\plugin"

如果用的是Connector C，命令改成：

gem install mysql2 -v 0.5.6 -- --with-mysql-dir="C:\Program Files\MySQL\Connector C 6.1"

3. 配置Bundler使用指定路径 #

如果上面的gem安装成功，直接运行bundle install即可；要是想让Bundler自动适配配置，先执行：

bundle config set --local build.mysql2 "--with-mysql-dir=C:\Program Files\MySQL\MySQL Server 8.0"
bundle install

4. 额外注意事项 #

• Ruby 3.0和mysql2 0.5.6是兼容的，无需更换版本
• 如果路径含空格导致报错，试试用短路径，比如C:\PROGRA~1\MySQL\MYSQLS~1.0
• 暂时关闭杀毒软件或防火墙，避免拦截编译过程
• 确保安装了Ruby DevKit或MSYS2（Windows编译原生扩展必需的工具链），RubyInstaller安装的Ruby可运行ridk install选择安装MSYS2和开发工具

临时替代方案（嫌编译麻烦可试） #

要是实在搞不定原生编译，试试预编译版本，修改Gemfile：

gem 'mysql2', platforms: [:mingw, :x64_mingw], git: 'https://github.com/brianmario/mysql2', ref: 'v0.5.6'

不过优先推荐前面的方法，预编译版本可能存在兼容性隐患。

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