Linux下C/C++连接MySQL：头文件与库文件安装及32/64位配置指南

简介：面向在 Linux 环境下进行 C/C++ 开发、需要连接 MySQL 数据库的开发者，这份资源提供编译期所需的头文件与链接库，免去安装 mysql-devel 或部署完整客户端与服务端的麻烦。压缩包共 77 个文件，以 68 个 .h 头文件、8 个 .a 静态库和 1 个 .so 动态库为主，分别对应接口声明与不同链接方式，整体约 16.49MB，并同时包含 32 位与 64 位两套目录，可按系统架构取用。使用时将头文件与库文件目录放入工程同级路径，在 Makefile 中通过 -I 与 -L 指向本地目录并链接 mysqlclient 及 pthread、m、dl 等依赖即可完成构建。资源已有 1143 人学习，适合需要快速搭建数据库连接编译环境、排查链接错误的开发者参考。

1. 编译报错先别急着换系统：Linux 下连 MySQL 的头文件和库文件到底怎么装

上周帮一位开发者看环境，代码里就一行#include <mysql.h>，gcc直接甩出fatal error: mysql.h: No such file or directory。他以为是系统缺东西，差点把整台机器重装。其实这类问题在 Linux 上太常见了：MySQL 服务端跑得好好的，客户端开发环境却没装全，头文件和库文件分属不同包，32 位和 64 位还各走各的路径。装不对，轻则编译不过，重则链接阶段报undefined reference to mysql_init，或者运行时加载到错误位宽的libmysqlclient.so，程序一启动就崩。这篇笔记面向正在 Linux 上写 C/C++ 连 MySQL 的开发者，把版本选择、头文件与库文件安装、编译参数、32/64 位共存和排错一次讲透，照着走能跑通。

2. 装之前先对齐版本：MySQL 客户端开发包与系统位数怎么选

2.1 先确认三件事：发行版、位数、MySQL 版本

动手装包之前，我一般强制先跑三条命令，把环境底账摸清。很多“装不上”的根因不是命令写错，而是一开始就没确认系统是 32 位还是 64 位、MySQL 是哪个大版本、包管理器是哪一套。

# 1. 看发行版和版本号，决定用 apt 还是 yum/dnf cat /etc/os-release # 2. 看内核和用户态位数，x86_64 表示 64 位系统 uname -m getconf LONG_BIT # 3. 看已安装的 MySQL 客户端/服务端版本 mysql --version

uname -m输出x86_64说明主系统是 64 位；getconf LONG_BIT输出32则说明当前用户态跑在 32 位环境里。这两个结果不一致时，后面选包要以getconf LONG_BIT为准，因为它反映的是编译器和库实际使用的位宽。mysql --version用来对齐开发包版本，客户端库的大版本最好和服务端一致，跨大版本链接虽然多数时候能跑，但遇到协议或结构体变化就会出玄学问题。

常见发行版的包名对照如下，装之前先心里有数：

这张表里最容易踩的是 Debian 系：64 位包叫libmysqlclient-dev，32 位要加:i386后缀，而且必须先启用多架构支持，否则apt根本找不到这个包。CentOS 系则要注意mysql-devel和mariadb-devel的取舍，两者头文件都叫mysql.h，但库名和 ABI 有差异，混装会出现链接到一半找不到符号的情况。

2.2 头文件和库文件为什么分两个包

很多人以为装了mysql-client就能开发，结果编译照样报错。原因是运行客户端和开发客户端是两回事：mysql-client只带命令行工具mysql，不带mysql.h和libmysqlclient.so的开发符号链接。开发需要的是-dev或-devel包，它才包含头文件目录、静态库、动态库以及供链接器使用的.so软链。

我一般这样理解：头文件负责“编译期认识函数长什么样”，库文件负责“链接期找到函数实现”。缺头文件报mysql.h: No such file，缺库文件报cannot find -lmysqlclient或undefined reference。两者缺一不可，而且位数必须和编译目标一致。用 64 位gcc编译却链了 32 位库，链接器会直接拒绝，报skipping incompatible。

2.3 版本差异：MySQL 8.0 与 5.7 的头文件位置变化

MySQL 8.0 之后，部分发行版把开发头文件从/usr/include/mysql挪到了/usr/include/mysql/mysql或者按版本号分目录，mysql_config --cflags的输出也跟着变。5.7 时代很多教程直接写-I/usr/include/mysql，到了 8.0 如果路径没对上，照样找不到头文件。稳妥做法是不手写路径，用mysql_config问系统要：

# 查询编译和链接参数，输出里带 -I 和 -L mysql_config --cflags mysql_config --libs

--cflags给出头文件搜索路径，--libs给出库搜索路径和库名。如果这条命令本身找不到，说明开发包没装或没进 PATH，先解决包的问题，别急着改 Makefile。我见过有人把-I/usr/include/mysql硬编码进 CMakeLists，换一台 8.0 的机器就翻车，用mysql_config是更省后悔药的做法。

3. 按发行版装开发包：头文件与库文件落地步骤

3.1 Debian/Ubuntu 下安装 64 位开发包

这是最常见的一类环境。先更新索引，再装开发包，最后验证头文件和库文件是否到位。

# 更新包索引 sudo apt update # 安装 MySQL 客户端开发包（64 位） sudo apt install -y libmysqlclient-dev # 验证头文件是否存在 ls -l /usr/include/mysql/mysql.h # 验证库文件是否存在 ls -l /usr/lib/x86_64-linux-gnu/libmysqlclient.so*

libmysqlclient-dev会自动带上libmysqlclient20或libmysqlclient21运行库作为依赖，不需要单独装。ls两条命令是装完后的第一道验收：头文件在/usr/include/mysql/下，库文件在/usr/lib/x86_64-linux-gnu/下，.so是给链接器用的软链，.so.21这类带版本号的是实际运行库。如果ls报不存在，先看apt输出里有没有“未安装任何软件包”之类的提示，多半是包名写错或源里没有。

装完顺手跑一次mysql_config --version，能输出版本号说明开发包的工具链也齐了。有些精简镜像里mysql_config被拆到单独包，缺了它后面 CMake 的FindMySQL模块会找不到库。

3.2 CentOS/RHEL 下安装 mysql-devel

CentOS 7 及更早版本用yum，RHEL 8 之后转向dnf，包名基本一致。注意 CentOS 7 官方源里 MySQL 相关包可能指向 MariaDB 的兼容包，装之前先确认来源。

# CentOS 7 安装 MySQL 开发包 sudo yum install -y mysql-devel # 如果源里只有 mariadb-devel，也能提供 mysql.h，但库名可能不同 sudo yum install -y mariadb-devel # 验证头文件和库文件 ls -l /usr/include/mysql/mysql.h ls -l /usr/lib64/libmysqlclient.so*

/usr/lib64是 64 位库的默认落点，32 位库在/usr/lib。mysql-devel和mariadb-devel二选一即可，但不要同时装，两者都提供mysql.h和libmysqlclient，文件冲突会让包管理器报错，强行覆盖后链接行为不可预期。我一般优先装与运行中服务端同源的开发包，服务端是 MySQL 就装mysql-devel，是 MariaDB 就装mariadb-devel。

如果yum提示找不到包，先确认是否启用了对应的软件源。CentOS 7 默认源里 MySQL 包版本较老，需要额外源才能拿到 8.0 的开发包，这一步按实际源配置来，不要盲目加第三方源。

3.3 用 mysql_config 生成编译参数并写进构建脚本

装好包之后，编译命令不要手写路径，用mysql_config动态取。下面是一个最小可编译示例，验证头文件和库文件是否真能协同工作。

# 写一个最小测试程序 cat > test_mysql.c <<'EOF' #include <mysql/mysql.h> #include <stdio.h> int main(void) { MYSQL *conn = mysql_init(NULL); if (conn == NULL) { printf("mysql_init failed\n"); return 1; } printf("mysql client version: %s\n", mysql_get_client_info()); mysql_close(conn); return 0; } EOF # 用 mysql_config 取参数编译 gcc test_mysql.c -o test_mysql $(mysql_config --cflags) $(mysql_config --libs) # 运行验证 ./test_mysql

$(mysql_config --cflags)展开后通常是-I/usr/include/mysql，$(mysql_config --libs)展开为-L/usr/lib/x86_64-linux-gnu -lmysqlclient。这样写的好处是换机器、换版本都不用改命令。注意#include的写法：有的环境头文件在/usr/include/mysql/mysql.h，代码里写<mysql.h>配合-I/usr/include/mysql能过；如果写<mysql/mysql.h>，则依赖/usr/include在默认搜索路径里。两种写法都常见，关键是和--cflags的输出对上，不要一半手写一半用工具。

运行输出客户端版本号，说明头文件、库文件、运行时加载三者全部打通。这一步过了，再往项目里集成就有底了。

4. 32 位与 64 位共存：多架构环境下的库文件配置

4.1 Debian/Ubuntu 启用 i386 多架构并安装 32 位开发包

32 位和 64 位库在 Debian 系里靠多架构机制共存，不是简单复制文件。默认只启用本机架构，要装 32 位包必须先声明i386。

# 启用 i386 架构支持 sudo dpkg --add-architecture i386 sudo apt update # 安装 32 位 MySQL 开发包 sudo apt install -y libmysqlclient-dev:i386 # 确认 32 位库落点 ls -l /usr/lib/i386-linux-gnu/libmysqlclient.so*

dpkg --add-architecture i386只是让包管理器认识这个架构，不会自动装任何东西，必须再apt update刷新索引。装完后 32 位库在/usr/lib/i386-linux-gnu/，64 位库在/usr/lib/x86_64-linux-gnu/，两者路径隔离，互不覆盖。头文件是架构无关的，通常共用/usr/include/mysql，所以编译 32 位程序时-I不用变，变的是-L和链接器目标。

用 32 位编译时，gcc要加-m32，并且系统里得有 32 位的 libc 开发包，否则会在更早的阶段报找不到crt1.o。这是另一个坑，和 MySQL 无关，但会伪装成“MySQL 装不上”。

4.2 用 -m32 编译并指定 32 位库路径

下面这段是 32 位编译的完整命令，重点在-m32和显式-L的顺序。

# 安装 32 位基础编译支持（Debian/Ubuntu） sudo apt install -y gcc-multilib g++-multilib # 用 32 位模式编译，库路径指向 i386 目录 gcc -m32 test_mysql.c -o test_mysql32 \ -I/usr/include/mysql \ -L/usr/lib/i386-linux-gnu \ -lmysqlclient # 用 file 确认产物位数 file test_mysql32

-m32让编译器生成 32 位目标文件，-L/usr/lib/i386-linux-gnu把链接器引到 32 位库目录，-lmysqlclient在該目录下找libmysqlclient.so。file输出里带32-bit才算成功。这里最容易翻车的是-L顺序：如果系统默认搜索路径里先命中 64 位库，链接器会报skipping incompatible /usr/lib/x86_64-linux-gnu/libmysqlclient.so，然后才是cannot find -lmysqlclient。看到skipping incompatible就说明位数对不上，不是库没装。

4.3 运行时库查找：LD_LIBRARY_PATH 与 ldconfig 的取舍

编译通过不代表运行通过。32 位程序启动时如果动态加载器找不到 32 位libmysqlclient.so，会报error while loading shared libraries。两种常见做法：临时用LD_LIBRARY_PATH，或写进ldconfig配置。

# 临时指定运行时库路径，只对当前命令生效 LD_LIBRARY_PATH=/usr/lib/i386-linux-gnu ./test_mysql32 # 永久方案：写入 ldconfig 配置并刷新缓存 echo "/usr/lib/i386-linux-gnu" | sudo tee /etc/ld.so.conf.d/mysql-i386.conf sudo ldconfig # 查看动态加载器实际找到的库 ldd ./test_mysql32 | grep mysql

LD_LIBRARY_PATH适合调试，不适合长期部署，因为它会污染子进程环境。ldconfig方案更干净，但要注意/etc/ld.so.conf.d/下的文件按字母序加载，路径不要和系统默认路径冲突。ldd是验证运行时链接的黑匣子，输出里如果libmysqlclient.so指向not found，说明路径没生效；如果指向 64 位库，说明加载到了错误位宽，程序会在启动阶段崩。

我一般先用LD_LIBRARY_PATH快速验证，确认程序逻辑没问题，再落到ldconfig。这样排错时能区分是“库找不到”还是“代码有问题”。

5. 避坑与排查：头文件库文件装完仍报错的五种情况

5.1 现象：fatal error: mysql.h: No such file or directory

原因通常是开发包没装，或者#include写法和-I路径不匹配。有人装了mysql-client就以为齐了，实际缺-dev包；也有人头文件在/usr/include/mysql/下，代码却写<mysql.h>又没加-I。

解决：先ls /usr/include/mysql/mysql.h确认文件在不在，不在就装开发包；在的话用mysql_config --cflags取路径，把-I加进编译命令。不要凭记忆手写路径，8.0 和 5.7 的落点可能不同。

5.2 现象：cannot find -lmysqlclient 或 skipping incompatible

原因分两种：库文件根本没装，或者装的是另一位宽的库。skipping incompatible是典型信号，链接器找到了库但位数不对，直接跳过。

解决：ls /usr/lib/x86_64-linux-gnu/libmysqlclient.so*和ls /usr/lib/i386-linux-gnu/libmysqlclient.so*分别确认两个位宽的库。编译 64 位程序却只装了 32 位包，就补装 64 位开发包；反之亦然。用file看库文件位数，比猜靠谱。

5.3 现象：编译通过，运行报 error while loading shared libraries

原因：编译期链接到了库，运行期动态加载器找不到，常见于 32 位程序或自定义安装路径。ldd一看便知。

解决：用ldd ./程序 | grep mysql看解析结果，not found就补LD_LIBRARY_PATH或写ldconfig配置。如果是自定义目录安装的 MySQL，库不在系统默认路径，必须显式告诉加载器。

5.4 现象：undefined reference to mysql_init 等符号

原因：头文件找到了，库也找到了，但链接顺序不对，或者链接的是静态库而依赖没带全。-lmysqlclient放在源文件之前，链接器可能已经扫过库，后面再出现的符号就没人解析。

解决：把-lmysqlclient放到编译命令末尾，源文件在前、库在后。用mysql_config --libs的输出顺序为准，不要自己调换。静态链接时还要补-lz -lssl -lcrypto等依赖，具体看mysql_config --libs是否带--static选项。

5.5 现象：同时装了 mysql-devel 和 mariadb-devel 后行为异常

原因：两个包都提供mysql.h和libmysqlclient，文件互相覆盖，头文件和库可能来自不同实现，ABI 不一致。

解决：卸载其中一个，保留与服务端同源的开发包。rpm -qf /usr/include/mysql/mysql.h能查出文件属于哪个包，据此决定去留。混装是血泪经验里最常见的一类，装的时候图省事，排错时查半天。

6. 装完怎么验证跑通：三条命令确认头文件、库文件、运行时全链路

装完包、配完路径，最后一步是验证。我习惯用三条命令把编译期、链接期、运行期串起来，任何一环断了都能立刻定位。先写一个带实际连接逻辑的最小程序，比只调mysql_init更能暴露问题。

cat > verify_mysql.c <<'EOF' #include <mysql/mysql.h> #include <stdio.h> int main(void) { MYSQL *conn = mysql_init(NULL); if (!conn) { printf("init failed\n"); return 1; } /* 只初始化，不真正连库，验证客户端库可用 */ printf("client version: %s\n", mysql_get_client_info()); printf("library version: %lu\n", mysql_get_client_version()); mysql_close(conn); return 0; } EOF # 64 位编译验证 gcc verify_mysql.c -o verify64 $(mysql_config --cflags) $(mysql_config --libs) ./verify64 # 32 位编译验证（需已启用 i386 并装 32 位开发包） gcc -m32 verify_mysql.c -o verify32 \ -I/usr/include/mysql \ -L/usr/lib/i386-linux-gnu -lmysqlclient LD_LIBRARY_PATH=/usr/lib/i386-linux-gnu ./verify32

mysql_get_client_info()返回字符串版本，mysql_get_client_version()返回数字版本，两者都来自实际链接的库，能输出就说明头文件和库文件版本对得上。64 位和 32 位各跑一遍，产物用file确认位数，运行时用ldd确认加载路径，这三条命令覆盖了从源码到进程的完整链路。

验证时还有两个细节值得盯。一是mysql_config --libs在部分环境会输出-Wl,-rpath之类的参数，直接塞进gcc没问题，但写进 Makefile 时要注意转义。二是容器环境里/usr/include/mysql可能是软链，ls -l看真实落点，避免挂载卷覆盖后头文件消失。我一般把验证程序留在项目tools/目录下，换机器先跑一遍，比翻文档快。

从那以后我每次配新环境，都强制先跑mysql_config --cflags和--libs，再编译一个最小程序，确认 32/64 位都对得上才动业务代码。这套习惯帮我省掉了大量“明明装了却报错”的来回。希望帮到你。

本文还有配套的精品资源，点击获取