執行 gem install mysql2 (或 mysql gem) 時編譯失敗，關鍵錯誤訊息：
checking for mysql_query() in -lmysqlclient... no
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary libraries and/or headers.根因：系統缺少 MySQL 客戶端開發函式庫 libmysqlclient-dev (Debian/Ubuntu) 或 mysql-devel (RHEL/CentOS/Fedora)，導致原生擴展無法編譯連結。
| 作業系統 | 套件管理器指令 | 套件名稱 |
|---|---|---|
| Ubuntu / Debian | sudo apt-get update && sudo apt-get install -y libmysqlclient-dev |
libmysqlclient-dev |
| CentOS / RHEL 7 | sudo yum install -y mysql-devel |
mysql-devel |
| CentOS / RHEL 8 / Fedora / Rocky / Alma | sudo dnf install -y mysql-devel |
mysql-devel |
| openSUSE | sudo zypper install -y libmysqlclient-devel |
libmysqlclient-devel |
| Alpine Linux | apk add --no-cache mariadb-dev |
mariadb-dev (相容 MySQL) |
| macOS (Homebrew) | brew install mysql-client 並配置 PKG_CONFIG_PATH |
mysql-client |
# 1. 驗證開發庫可用
mysql_config --version
mysql_config --libs
mysql_config --cflags
# 2. 重新安裝 gem (會自動偵測 mysql_config)
gem install mysql2
# 3. 或指定 mysql_config 路徑 (非標準安裝位置)
gem install mysql2 -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
# 4. Bundler 專案
bundle config build.mysql2 --with-mysql-config=/usr/local/mysql/bin/mysql_config
bundle install| 現象 | 原因 | 解決 |
|---|---|---|
仍報 mysql_query() ... no |
mysql_config 不在 PATH、或指向錯誤版本 |
which mysql_config、export PATH=$PATH:/usr/local/mysql/bin |
ld: library not found for -lmysqlclient |
運行時動態庫路徑缺失 | echo "/usr/local/mysql/lib" > /etc/ld.so.conf.d/mysql.conf && ldconfig |
| 多 MySQL 版本衝突 | 系統庫 vs 官方庫版本不符 | 統一使用官方 MySQL 套件，或 Docker 容器化隔離 |
| Apple Silicon (M1/M2) 編譯失敗 | 架構不匹配 (arm64 vs x86_64) | arch -x86_64 gem install mysql2 或使用原生 arm64 MySQL (Homebrew) |
Rails 專案 LoadError: libmysqlclient.so |
部署環境缺少 runtime 庫 | Dockerfile 安裝 libmysqlclient21 / mysql-libs |
# Dockerfile 片段
FROM ruby:3.2-slim
# 安裝 MySQL 客戶端開發庫 + runtime 庫
RUN apt-get update && apt-get install -y --no-install-recommends \
libmysqlclient-dev \
default-mysql-client \
&& rm -rf /var/lib/apt/lists/*
# 安裝 gem
RUN gem install mysql2 -v 0.5.6
# 或使用官方 MySQL 映像建構階段
# FROM mysql:8.0 AS mysql-builder
# COPY --from=mysql-builder /usr/include/mysql /usr/include/mysql
# COPY --from=mysql-builder /usr/lib/mysql /usr/lib/mysqlgem 'mysql2'：原生擴展，效能最好，**需編譯環境**gem 'ruby-mysql'：純 Ruby 實現，**無需編譯**，效能較低，適合開發/測試/無編譯環境gem 'sequel' + mysql2：ORM 層面選擇Gem 安裝 mysql2 失敗 99% 為缺少 libmysqlclient-dev 開發套件。安裝對應發布版的 MySQL 開發庫、驗證 mysql_config 可用、重裝 gem 三步驟即可解決。生產部署建議使用 Docker 鎖定編譯與運行環境一致性，避免「開發機正常、部署機失敗」的經典陷阱。
