Ubuntu环境下bundle install失败：mysql2原生扩展构建错误求助

问题概述 #

运行已有Ruby on Rails项目时，执行bundle install失败，无法安装mysql2 0.4.6 gem，报错核心为undefined method 'split' for nil:NilClass。

报错详情 #

Fetching mysql2 0.4.6
Installing mysql2 0.4.6 with native extensions
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    current directory: /home/vince/.rbenv/versions/2.7.6/lib/ruby/gems/2.7.0/gems/mysql2-0.4.6/ext/mysql2
/home/vince/.rbenv/versions/2.7.6/bin/ruby -I /home/vince/.rbenv/versions/2.7.6/lib/ruby/2.7.0 -r ./siteconf20221031-7332-kotkbi.rb extconf.rb
checking for rb_absint_size()... yes
checking for rb_absint_singlebit_p()... yes
checking for ruby/thread.h... yes
checking for rb_thread_call_without_gvl() in ruby/thread.h... yes
checking for rb_thread_blocking_region()... no
checking for rb_wait_for_single_fd()... yes
checking for rb_hash_dup()... yes
checking for rb_intern3()... yes
checking for rb_big_cmp()... yes
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

Provided configuration options:
        --with-opt-dir
        --without-opt-dir
        --with-opt-include
        --without-opt-include=${opt-dir}/include
        --with-opt-lib
        --without-opt-lib=${opt-dir}/lib
        --with-make-prog
        --without-make-prog
        --srcdir=.
        --curdir
        --ruby=/home/vince/.rbenv/versions/2.7.6/bin/$(RUBY_BASE_NAME)
        --with-ruby-dir
        --without-ruby-dir
        --with-ruby-include
        --without-ruby-include=${ruby-dir}/include
        --with-ruby-lib
        --without-ruby-lib=${ruby-dir}/lib
        --with-mysql-dir
        --without-mysql-dir
        --with-mysql-include
        --without-mysql-include=${mysql-dir}/include
        --with-mysql-lib
        --without-mysql-lib=${mysql-dir}/lib
        --with-mysql-config
        --without-mysql-config
        --with-mysqlclient-dir
        --without-mysqlclient-dir
        --with-mysqlclient-include
        --without-mysqlclient-include=${mysqlclient-dir}/include
        --with-mysqlclient-lib
        --without-mysqlclient-lib=${mysqlclient-dir}/lib
        --with-mysqlclientlib
        --without-mysqlclientlib
/home/vince/.rbenv/versions/2.7.6/lib/ruby/2.7.0/mkmf.rb:1050:in `block in find_library': undefined method `split' for nil:NilClass (NoMethodError)
        from /home/vince/.rbenv/versions/2.7.6/lib/ruby/2.7.0/mkmf.rb:1050:in `collect'
        from /home/vince/.rbenv/versions/2.7.6/lib/ruby/2.7.0/mkmf.rb:1050:in `find_library'
        from extconf.rb:95:in `<main>'

To see why this extension failed to compile, please check the mkmf.log which can be found here:

  /home/vince/.rbenv/versions/2.7.6/lib/ruby/gems/2.7.0/extensions/x86_64-linux/2.7.0/mysql2-0.4.6/mkmf.log

extconf failed, exit code 1

Gem files will remain installed in /home/vince/.rbenv/versions/2.7.6/lib/ruby/gems/2.7.0/gems/mysql2-0.4.6 for inspection.
Results logged to /home/vince/.rbenv/versions/2.7.6/lib/ruby/gems/2.7.0/extensions/x86_64-linux/2.7.0/mysql2-0.4.6/gem_make.out

An error occurred while installing mysql2 (0.4.6), and Bundler cannot continue.
Make sure that `gem install mysql2 -v '0.4.6' --source 'https://rubygems.org/'` succeeds before bundling.

In Gemfile:
  mysql2

环境信息 #

• Ruby版本：2.7.6
• Rails版本：5.0.7.2
• 操作系统：Ubuntu 20.04

原因分析 #

报错核心undefined method 'split' for nil:NilClass表明，mysql2 gem在编译native扩展时，尝试调用split方法处理某个空值，本质是缺少MySQL开发依赖库，导致gem无法找到必要的头文件和库文件，进而无法生成Makefile完成编译。

解决步骤 #

1. 安装MySQL开发依赖与编译工具 #

Ubuntu 20.04下执行以下命令安装必备依赖：

sudo apt update
sudo apt install libmysqlclient-dev build-essential

2. 手动指定mysql-config路径安装gem #

若安装依赖后仍失败，手动指定mysql-config的路径进行安装：
首先查找mysql-config位置：

which mysql-config

假设输出为/usr/bin/mysql-config，执行：

gem install mysql2 -v '0.4.6' -- --with-mysql-config=/usr/bin/mysql-config

安装成功后再执行bundle install。

3. 清理残留gem缓存（可选） #

若之前的安装残留导致冲突，先清理再重新安装：

gem uninstall mysql2 -v '0.4.6'
rm -rf /home/vince/.rbenv/versions/2.7.6/lib/ruby/gems/2.7.0/gems/mysql2-0.4.6

4. 确认MySQL服务状态（可选） #

如果项目依赖本地MySQL服务，确保服务已安装并启动：

sudo apt install mysql-server
sudo systemctl start mysql

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