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

1. 编译报错先别急着换系统：Linux 下连 MySQL 的头文件和库文件，32 位和 64 位到底差在哪

上周帮一位做嵌入式网关的开发者排查编译问题，现象很典型：同一份 C 代码，在开发机上gcc一把过，挪到目标板交叉编译环境里就报fatal error: mysql.h: No such file or directory，把-I指到/usr/include/mysql之后又变成undefined reference to mysql_init。他一度怀疑是 MySQL 版本装错了，重装了两遍客户端，问题照旧。真正的原因其实很朴素——头文件是 64 位开发包带的，链接时却按 32 位去找库，路径和 ABI 全对不上。

Linux 下开发连 MySQL，绕不开三样东西：mysql.h这类头文件、libmysqlclient.so这类库文件、以及它们对应的 32 位与 64 位两套产物。装不好不会立刻报错，往往在链接阶段才翻车，排查成本比安装本身高得多。这篇笔记按「先看清环境 → 装对开发包 → 配编译参数 → 验证能跑 → 坏了怎么救」的顺序走一遍，适合刚接手 C/C++ 服务端项目、或者要给老系统补 32 位兼容的开发者照着复现。

2. 环境与版本先对齐：头文件、库文件、位数三件事

2.1 先确认系统位数和编译器默认目标

动手装包之前，先把「我是谁、我要编给谁」弄清楚。很多链接错误不是包没装，而是编译器和库的位数不一致。常见做法是先看内核架构和编译器默认输出：

# 查看内核与用户态架构，x86_64 表示 64 位系统 uname -m # 查看 gcc 默认生成的目标位数，输出类似 elf64-x86-64 gcc -dumpmachine # 确认系统里是否装了 32 位运行库支持 ls /lib/ld-linux.so.2 2>/dev/null && echo "32位运行库已就绪"

uname -m给出的是内核架构，gcc -dumpmachine给出的是编译器默认三元组，两者要一起看。如果目标是 32 位程序，gcc -m32能否成功编译一个空main是最快的探针，缺gcc-multilib时会直接报找不到bits/c++config.h之类。这一步的意义在于：后面选libmysqlclient-dev还是libmysqlclient-dev:i386，完全取决于这里的结果，先定方向再装包，能省掉一轮卸载重装。

2.2 头文件和库文件分别落在哪

MySQL 的开发产物在 Linux 上通常分两处：头文件在/usr/include/mysql/，库文件在/usr/lib/x86_64-linux-gnu/（Debian 系）或/usr/lib64/（RHEL 系）。32 位库一般落在/usr/lib/i386-linux-gnu/或/usr/lib/。装完包先别急着写代码，用两条命令把位置钉死：

# 找头文件，确认 mysql.h 的真实路径 find /usr/include -name "mysql.h" 2>/dev/null # 找库文件，同时看 32 位和 64 位是否都在 find /usr/lib /usr/lib64 /usr/lib/i386-linux-gnu -name "libmysqlclient*" 2>/dev/null

find的结果要重点看后缀：libmysqlclient.so是链接时用的符号链接，libmysqlclient.so.21这类带版本号的是运行时真正加载的实体。如果只找到.so.21而没有.so，说明只装了运行时包、没装开发包，链接必然失败。这一步的输出建议直接记下来，后面写-I和-L时照抄，比凭记忆猜路径靠谱。

2.3 版本选择：客户端库和服务器版本不必强绑

一个常见误解是「服务器装的是 MySQL 8.0，客户端库也必须 8.0」。实际上libmysqlclient的 ABI 在 5.7 到 8.0 之间有变化，但编译期只需要头文件和库的版本一致即可，运行时连哪个版本的服务器由连接串决定。我一般会遵循两条：编译用的头文件和链接的库必须来自同一个开发包；如果项目还要兼容老服务器，优先选发行版仓库里那个被大量项目验证过的版本，而不是追最新。

表里最容易被忽略的是 RHEL 系的库路径多了一层mysql子目录，直接写-L/usr/lib64有时能过、有时不能，取决于发行版是否做了兼容软链。稳妥做法是以find的实际输出为准，不要照搬网上抄来的路径。

3. 安装开发包：64 位与 32 位两套产物的落地步骤

3.1 Debian/Ubuntu 下装 64 位开发包

先更新索引再装，避免拿到过期的包元数据。安装命令本身很短，但要留意输出里有没有「已是最新版本」——如果之前装过运行时包，开发包可能被依赖关系挡住：

# 更新包索引 sudo apt-get update # 安装 64 位 MySQL 客户端开发包，含头文件与 .so 链接 sudo apt-get install -y libmysqlclient-dev # 验证头文件与库文件是否同时到位 dpkg -L libmysqlclient-dev | grep -E "mysql.h|libmysqlclient.so$"

dpkg -L列出的是包内文件清单，用它验证比find更直接：能同时看到mysql.h和libmysqlclient.so，说明开发包完整。如果只看到头文件没有.so，多半是包被拆分了，需要额外装libmysqlclient20之类的运行时包。-y只是免交互，生产环境我一般去掉它，先看一眼将要安装的版本号再确认。

3.2 补 32 位开发包：先开架构再装

32 位开发包不是默认就能装的，Debian 系要先声明i386架构，否则apt会直接告诉你「无法定位软件包」。这一步的顺序不能反，先dpkg --add-architecture再update：

# 声明支持 i386 架构 sudo dpkg --add-architecture i386 # 重新拉取索引，让 apt 认识 i386 的包 sudo apt-get update # 安装 32 位开发包 sudo apt-get install -y libmysqlclient-dev:i386 # 确认 32 位库文件落地 ls -l /usr/lib/i386-linux-gnu/libmysqlclient.so

这里有个血泪经验：libmysqlclient-dev:i386和 64 位版本共用/usr/include/mysql下的头文件，头文件本身通常不分位数，所以-I只需要写一次；真正分家的是-L指向的库目录。装完 32 位包后如果ls报「没有那个文件」，先检查dpkg --print-foreign-architectures是否真的输出了i386，架构没生效时apt会静默跳过。

3.3 RHEL/CentOS 系的对应装法

RHEL 系用yum或dnf，包名是mysql-devel，32 位用.i686后缀。注意这类系统里 MySQL 和 MariaDB 的开发包可能冲突，装之前先确认仓库里提供的是哪一个：

# 查看可用的开发包及其架构 yum list available mysql-devel mariadb-devel 2>/dev/null # 安装 64 位开发包 sudo yum install -y mysql-devel # 安装 32 位开发包 sudo yum install -y mysql-devel.i686 # 验证库文件位置 ls -l /usr/lib64/mysql/libmysqlclient.so /usr/lib/mysql/libmysqlclient.so

yum list那一步是为了避免装成 MariaDB 的兼容包——两者头文件同名但部分结构体字段有差异，混用会在编译期报「结构体成员不存在」。如果仓库里只有mariadb-devel，那就统一用它，别一半 MySQL 一半 MariaDB。装完用ls同时确认两个路径，缺哪个补哪个。

4. 编译参数怎么配：-I、-L、-l 三个开关的取舍

4.1 最小可编译示例与参数含义

装好包之后，用一个最小程序把编译链路跑通，比直接上项目代码更容易定位问题。下面这段代码只做初始化和清理，不真正连库，用来验证头文件和库能否被正确找到：

/* mysql_probe.c —— 仅验证头文件与库文件可被编译链接 */ #include <mysql/mysql.h> #include <stdio.h> int main(void) { /* mysql_init 传 NULL 表示由库自行分配连接句柄 */ MYSQL *conn = mysql_init(NULL); if (conn == NULL) { fprintf(stderr, "mysql_init failed\n"); return 1; } printf("mysql client version: %s\n", mysql_get_client_info()); mysql_close(conn); return 0; }

编译命令要按位数分开写，64 位和 32 位的差别只在-m32和-L路径：

# 64 位编译 gcc mysql_probe.c -o probe64 \ -I/usr/include/mysql \ -L/usr/lib/x86_64-linux-gnu \ -lmysqlclient # 32 位编译，注意 -m32 与 32 位库路径必须同时出现 gcc -m32 mysql_probe.c -o probe32 \ -I/usr/include/mysql \ -L/usr/lib/i386-linux-gnu \ -lmysqlclient

-I告诉预处理器去哪找mysql.h，-L告诉链接器去哪找libmysqlclient.so，-l是库名去掉lib前缀和.so后缀。三者缺一不可，而且-L的路径必须和-m32匹配——只加-m32不加 32 位-L，链接器会去 64 位目录找库然后报「文件格式不匹配」。mysql_get_client_info()返回的是客户端库版本，能打印出来就说明链接成功。

4.2 用 pkg-config 少写死路径

手写-I和-L在单机上没问题，换台机器路径一变就得改 Makefile。更稳的做法是用pkg-config，前提是开发包带了.pc文件：

# 查看 pkg-config 能否识别 mysqlclient pkg-config --cflags --libs mysqlclient # 在编译命令里直接引用 gcc mysql_probe.c -o probe $(pkg-config --cflags --libs mysqlclient)

--cflags输出头文件路径，--libs输出库路径和库名。如果命令报「Package mysqlclient was not found」，说明.pc文件没装或不在默认搜索路径，可以用PKG_CONFIG_PATH指过去。32 位场景下pkg-config默认仍可能返回 64 位路径，这时要么手动覆盖，要么老老实实写死-L，别指望它自动识别-m32。

4.3 运行时库路径：编译过了不等于跑得起来

编译链接成功只是第一步，程序运行时还要能找到libmysqlclient.so.21这类带版本号的实体库。如果库装在非标准路径，启动时会报error while loading shared libraries。两种处理方式，按场景选：

# 方式一：临时指定，仅对当前命令生效，适合排查 LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu ./probe64 # 方式二：写入系统配置并刷新缓存，适合长期部署 echo "/usr/lib/x86_64-linux-gnu" | sudo tee /etc/ld.so.conf.d/mysql-client.conf sudo ldconfig

LD_LIBRARY_PATH优先级高但只影响当前进程，适合验证阶段快速确认「是不是库路径问题」。ld.so.conf.d加ldconfig是持久化做法，改完用ldd ./probe64 | grep mysql确认解析到了正确路径。我一般先用方式一确认问题根因，再决定要不要落方式二，避免把错误路径写进系统配置。

5. 避坑与排查：五条真实踩过的记录

5.1 现象：编译报 mysql.h 找不到，但文件明明存在

原因通常是-I写成了/usr/include而不是/usr/include/mysql，而代码里写的是#include <mysql.h>。头文件在mysql子目录下，包含方式必须和-I配合。解决方式二选一：代码改成#include <mysql/mysql.h>且-I/usr/include，或者保持#include <mysql.h>且-I/usr/include/mysql。两种都行，但项目里要统一，混用会在多人协作时反复翻车。

5.2 现象：undefined reference to mysql_init

头文件找到了、编译过了，链接阶段报未定义符号。原因基本是-lmysqlclient缺失或顺序不对——gcc的链接顺序敏感，库要放在源文件之后。另一个可能是只装了运行时包没装开发包，.so符号链接不存在。解决：确认-lmysqlclient在命令末尾，用find确认libmysqlclient.so存在，缺则补装开发包。

5.3 现象：32 位编译报「文件格式不匹配」

-m32加了，但-L还指向 64 位库目录，链接器读到 64 位 ELF 直接拒绝。原因是指路径时没跟着位数走。解决：32 位编译必须配 32 位-L，并用file命令确认目标库确实是 32 位：file /usr/lib/i386-linux-gnu/libmysqlclient.so应输出ELF 32-bit。这一步能快速排除「装错包」和「路径写错」两种可能。

5.4 现象：程序启动报 cannot open shared object file

编译链接都过了，运行时报找不到共享库。原因是运行时加载器不认编译期的-L路径，它只查ld.so.conf和默认目录。解决：用ldd看程序实际在找哪个路径，再用LD_LIBRARY_PATH临时验证，确认后写入ld.so.conf.d并ldconfig。注意别把开发目录长期塞进LD_LIBRARY_PATH，容易和系统库串版本。

5.5 现象：MySQL 和 MariaDB 开发包混装后结构体报错

编译时报某个结构体成员不存在，或函数签名不匹配。原因是系统里同时存在两套头文件，-I指到了其中一套、-l链到了另一套。解决：用dpkg -l | grep -E "mysql|mariadb"或rpm -qa | grep -E "mysql|mariadb"列出所有相关包，卸掉不需要的那套，只保留一套开发包，然后重新确认头文件和库来自同一来源。

6. 装完怎么验证跑通：三步确认法

验证不能只看「编译没报错」，要分三层确认：编译期找得到、链接期链得上、运行期加载得到。我习惯用一个脚本把三步串起来，每次换环境都跑一遍，比凭记忆敲命令稳。

#!/bin/bash # verify_mysql_client.sh —— 三步确认 MySQL 客户端开发环境可用 set -e BIT=${1:-64} # 传入 32 或 64，默认 64 位 if [ "$BIT" = "32" ]; then MFLAG="-m32" LIBDIR="/usr/lib/i386-linux-gnu" else MFLAG="" LIBDIR="/usr/lib/x86_64-linux-gnu" fi # 第一步：头文件是否存在 test -f /usr/include/mysql/mysql.h || { echo "头文件缺失"; exit 1; } # 第二步：编译链接最小程序 gcc $MFLAG mysql_probe.c -o /tmp/probe_$BIT \ -I/usr/include/mysql -L$LIBDIR -lmysqlclient # 第三步：运行并检查动态库解析 /tmp/probe_$BIT ldd /tmp/probe_$BIT | grep mysqlclient

脚本里BIT参数决定-m32和库目录，set -e保证任一步失败立即停。第三步的ldd输出要重点看箭头指向的路径是不是你期望的那个库目录，如果指向了系统里另一份旧版本，说明ldconfig缓存里有残留，需要清理后重跑。这个脚本我一般放在项目scripts/下，新人拉代码后先跑它，能省掉大量「我这编译不过」的来回沟通。

还有一个容易被忽略的验证点：真正连一次数据库。最小程序只验证了库能加载，没验证协议层。补一个带连接串的测试，把主机、端口、用户、密码通过环境变量传入，能连上再mysql_close，才算整条链路通了。连接失败时先看错误码，2002是 socket 或端口不通，1045是认证失败，两者排查方向完全不同，别一上来就怀疑库装错了。

从那以后我每次给新环境配 MySQL 开发依赖，都强制先跑一遍这个三步脚本再动项目代码——头文件、库文件、位数这三件事只要有一件没对齐，后面写多少业务逻辑都是白费。希望帮到你。

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