Mac M1下Ruby2.6.4+mysql2 0.5.3构建Rails应用遇LoadError如何解决？

问题重现 #

在Mac M1（arm64）机器上升级Ruby到2.6.4、mysql2到0.5.3后，执行bundle exec rails server时出现以下错误：

require': dlopen(/vendor/bundle/ruby/2.6.0/extensions/-darwin-21/2.6.0/mysql2-0.5.3/mysql2/mysql2.bundle, 0x0009): symbol not found in flat namespace (_mysql_affected_rows) - /vendor/bundle/ruby/2.6.0/extensions/-darwin-21/2.6.0/mysql2-0.5.3/mysql2/mysql2.bundle (LoadError)

解决方案 #

以下是针对该问题的逐一排查步骤：

1. 彻底清理旧编译产物 #

先清除所有与mysql2 0.5.3相关的旧文件，避免残留影响：

• 卸载gem：

  gem uninstall mysql2 -v 0.5.3
  

• 删除Ruby版本下的mysql2安装目录：

  rm -rf ~/.rbenv/versions/2.6.4/lib/ruby/gems/2.6.0/gems/mysql2-0.5.3
  rm -rf ~/.rbenv/versions/2.6.4/lib/ruby/gems/2.6.0/extensions/-darwin-21/2.6.0/mysql2-0.5.3
  

• 删除项目下的vendor bundle：

  rm -rf vendor/bundle
  

2. 确保所有组件为arm64架构 #

验证Ruby架构

执行以下命令确认Ruby是arm64版本：

file $(which ruby)

输出需包含arm64，如果显示x86_64，说明Ruby是通过Rosetta编译的，需重新安装：

rbenv uninstall 2.6.4
# 确保终端为arm64模式（执行`arch`输出arm64）
arch
# 重新安装Ruby，指定openssl依赖（Ruby 2.6需用openssl@1.1）
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)" rbenv install 2.6.4

验证MySQL架构

确认MySQL是arm64版本：

file $(brew --prefix mysql)/bin/mysql

输出需包含arm64，若不是，重新安装arm64版本的MySQL：

brew uninstall mysql
brew install mysql

3. 正确设置编译环境变量并重新编译mysql2 #

在arm64终端下设置环境变量，确保编译时链接到正确的arm64 MySQL库：

export ARCHFLAGS="-arch arm64"
export LDFLAGS="-L$(brew --prefix mysql)/lib"
export CPPFLAGS="-I$(brew --prefix mysql)/include"
export PATH="$(brew --prefix mysql)/bin:$PATH"

然后重新安装mysql2：

gem install mysql2 -v '0.5.3' -- --with-mysql-config=$(brew --prefix mysql)/bin/mysql_config

或者通过bundle安装，先修改.bundle/config为以下内容（统一使用M1 brew的/opt/homebrew路径，不要混用/usr/local）：

BUNDLE_BUILD__MYSQL2: "--with-mysql-config=/opt/homebrew/opt/mysql/bin/mysql_config --with-ldflags=-L/opt/homebrew/opt/mysql/lib --with-cppflags=-I/opt/homebrew/opt/mysql/include"

再执行：

bundle install

4. 检查动态库链接路径 #

验证mysql2.bundle链接的MySQL库是否正确：

otool -L vendor/bundle/ruby/2.6.0/extensions/-darwin-21/2.6.0/mysql2-0.5.3/mysql2/mysql2.bundle

输出中的MySQL库路径应指向/opt/homebrew/opt/mysql/lib下的arm64库，若出现/usr/local路径的库，说明编译时未找到正确的arm64库，需重复步骤2-3。

5. 尝试切换MySQL版本 #

若上述步骤无效，可尝试切换到mysql@5.7（mysql2 0.5.3对其兼容性更稳定）：

brew unlink mysql
brew link --force mysql@5.7
# 重复步骤3的编译操作

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