MacOS下启动Rails服务器报cannot load such file -- mysql2/mysql2错误如何解决

第一步：修复版本兼容性问题 #

Rails 4.2.x 版本最高仅支持 0.4.x 系列的 mysql2 gem，你当前配置的 0.5.2 版本超出适配范围，是触发加载错误的核心原因。

操作步骤：

• 修改 Gemfile 中的 mysql2 版本约束：

  gem 'mysql2', '~> 0.4.10'
  

• 卸载已安装的高版本 mysql2：
  gem uninstall mysql2 -v 0.5.2
  弹出依赖提示时直接确认卸载即可
• 重新执行项目依赖安装：
  bundle install

第二步：MacOS 环境下重新编译原生扩展（若第一步执行后仍报错） #

mysql2 需要编译原生扩展关联本地 MySQL 库，MacOS 下如果路径识别异常会触发加载失败，可手动指定路径重装：

• Intel 芯片 Mac 执行：
  gem install mysql2 -v '0.4.10' -- --with-mysql-config=/usr/local/opt/mysql/bin/mysql_config
• M1/M2 系列 ARM 芯片 Mac 执行：
  gem install mysql2 -v '0.4.10' -- --with-mysql-config=/opt/homebrew/opt/mysql/bin/mysql_config

额外校验操作 #

• 执行 rake 命令或启动 Rails 服务时，统一添加 bundle exec 前缀，确保调用的是当前项目绑定的 gem 版本，示例：bundle exec rake -T、bundle exec rails s
• 如果你使用 rbenv 管理 Ruby 版本，重装 gem 后执行 rbenv rehash 更新可执行文件映射

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