简介：面向 Linux 平台 MySQL 数据库连接开发的配套依赖包，主要服务使用 C 语言访问 MySQL 的开发者，也适合课程实验、小型项目及离线编译环境准备。包内按 32 位与 64 位系统分别整理头文件和库文件，可省去额外查找 mysql-devel 或安装客户端、服务端的麻烦，在联网受限或环境不完整的机器上也能较快补齐编译链接所需的依赖。全部文件共 77 个，以 68 个 .h 头文件、8 个 .a 静态库和 1 个 .so 动态库为主，压缩包约 16.49MB，体积轻便，按位数分目录存放，便于根据目标平台取用。头文件提供接口声明，静态库与动态库对应不同链接方式，对理解 MySQL C API 的依赖组成、完成本地构建和验证 32/64 位适配均有参考价值，也能减少环境配置中反复试错的成本。已有 1144 人学习，适合初中级 Linux C 开发者用于项目环境准备与编译依赖整理。

1. 从头文件报错说起：Linux 下连 MySQL 的 32/64 位差异到底卡在哪

第一次在 Linux 上写连库程序，十有八九卡在同一处：fatal error: mysql.h: No such file or directory。老老实实补上-I之后，编译器不喊了，链接器接着喊cannot find -lmysqlclient；等你要出一个 32 位目标再编一遍，前面两步全部作废重来。linux mysql头文件 和 mysql库文件 这两件事的麻烦不在于难，而在于它们跟架构位数、目录约定、包的拆分方式三件事绑死，任何一处对不上就是一条报错。

这份资源对准的就是这三处对齐：头文件到底装在哪、库文件在 64 位和 32 位下分别落在哪个目录、编译链接参数怎么写、跑起来找不到.so该往哪查。适合刚接手 C/C++ 服务端项目、要在同一台机器上同时出 32 位和 64 位产物的人，也适合机器上同时躺着两三个 MySQL 客户端的场景。后面按「先认清文件 → 再装依赖 → 再写参数 → 最后排错」的顺序推。

2. 32 位和 64 位不是换个参数：头文件与库文件的目录差在哪

2.1 头文件与库文件在编译链路里各管一段

把一次构建拆开看，mysql.h和libmysqlclient.so根本不在同一个阶段出场。预处理器阶段只认-I给的目录，按顺序在里头找<>里的头文件；链接阶段只认-L给的目录和-l给的名字，去找libmysqlclient.so或libmysqlclient.a；程序跑起来之后，动态加载器又按另一套规则（ld.so.cache、LD_LIBRARY_PATH、DT_RPATH）去找那个.so。三个阶段、三套搜索路径，任何一环指错了目录，报错长得完全不一样，这也是为什么很多人改了一个参数、错误换了个模样，却还是没编过。

位数这件事只影响后两环。头文件绝大多数与架构无关，mysql.h在 32 位和 64 位机器上是同一份；真正分架构的是库文件，因为.so是 ELF 格式，文件头里写死了ELF32还是ELF64、Intel 80386还是x86-64。链接器拿到一个位数不匹配的.so，不会报「找不到」，而是打一行skipping incompatible，然后继续找下一个，最后统一给你一句cannot find -lmysqlclient——这就是最容易误导人的地方。

所以排查顺序应该是：头文件路径对不对（编译期），库目录里的文件位数对不对（链接期），运行时加载到的是不是同一份（运行期）。三件事分开验证，比一次性调参数快得多。

2.2 64 位与 32 位库文件的默认落点

同样是 64 位系统，rpm 系和 apt 系的目录约定完全不同，这是跨机器迁移构建脚本时最常见的翻车点。

表里能看出一个规律：64 位目录在 rpm 系靠lib64后缀区分，在 apt 系靠三元组目录名区分；32 位则统一走另一条路径。这意味着你没法用一套-L通吃，交叉出 32 位产物时必须把-L换成 32 位那一份。

还有两个细节要注意。一是库文件名里的 soname 编号会随大版本变化，libmysqlclient.so是个软链接，真正被依赖的是libmysqlclient.so.xx，所以构建脚本里永远写-lmysqlclient，不要写死带编号的文件名。二是静态库libmysqlclient.a通常和.so放在同一个目录，-l的优先级是动态库在前、静态库在后，想要静态链接必须显式指定。

2.3 三条命令确认一个库文件到底是几位

不要靠目录名猜位数，直接用工具读文件头。下面这段在任意一台 Linux 上都能跑：

# 1. 粗看：file 会直接把 ELF 位数和 CPU 架构打出来 file /usr/lib64/mysql/libmysqlclient.so # 期望输出形如：ELF 64-bit LSB shared object, x86-64 ... # 2. 细看：readelf 读 ELF 头，Class 和 Machine 两行最关键 readelf -h /usr/lib/x86_64-linux-gnu/libmysqlclient.so | grep -E 'Class|Machine' # 64 位：Class: ELF64 / Machine: Advanced Micro Devices X86-64 # 32 位：Class: ELF32 / Machine: Intel 80386 # 3. 换个角度：反查一个已知能连库的可执行文件依赖了哪份 so ldd /usr/bin/mysql | grep mysqlclient

file适合快速判断，readelf -h适合写进脚本做断言，ldd适合确认「系统上那个能跑的程序到底用了哪一份」。三者的区别在于：前两个看文件本身，第三个看运行时实际解析结果——当机器上装了多份客户端库时，只有ldd能告诉你真相。

如果手头没有现成的库文件，也可以反过来问编译器它会去哪找：

# 查看 64 位和 32 位各自的库搜索路径 gcc -print-search-dirs | grep libraries gcc -m32 -print-search-dirs | grep libraries # 让 gcc 直接告诉你某个库在 32 位模式下解析到哪个绝对路径 gcc -m32 -print-file-name=libmysqlclient.so

-print-file-name这个用法值得记住：如果它原样返回libmysqlclient.so而不是一个绝对路径，说明编译器在 32 位搜索路径里根本没找到这个库，后面链接必定失败，可以省掉一轮试错。

3. 装依赖与定位文件：三条命令确认 mysql.h 和 libmysqlclient.so 的真实路径

3.1 用包管理器把 devel 包装上

头文件和.so的软链接通常不在运行时包里，而在名字带devel或dev的开发包里。只装客户端或服务端，能跑程序但编不了程序，这是新手最常踩的第一个坑。

apt 系：

# 更新索引后安装开发包；default-libmysqlclient-dev 是兼容实现的兜底选择 sudo apt-get update sudo apt-get install -y libmysqlclient-dev # 如果源里没有上面这个包，用兼容实现提供的同名开发包 sudo apt-get install -y default-libmysqlclient-dev # 确认包装了什么：头文件、so 软链接、静态库都会列出来 dpkg -L libmysqlclient-dev | grep -E 'mysql\.h|libmysqlclient'

rpm 系：

# 安装开发包 sudo dnf install -y mysql-devel # 查询包内文件清单，确认头文件与库的实际路径 rpm -ql mysql-devel | grep -E 'mysql\.h|libmysqlclient'

这两段命令的重点不在安装本身，而在后半段的清单查询。不同发行版打包时会把头文件塞进/usr/include/mysql或/usr/include/mariadb，把库塞进/usr/lib64/mysql或/usr/lib64，靠猜容易出错，直接问包管理器最快。装完之后立刻跑一次清单查询，把路径记下来，后面写编译参数就不用再翻。

提示：只装mysql或mysql-client这类运行时包，mysql.h是不会出现的。看到「头文件找不到」先确认开发包在不在，再谈路径问题。

3.2 32 位库从哪来：多架构与自行编译

64 位系统上默认只有 64 位库，这是常态。想出 32 位产物，得先让 32 位的libmysqlclient落到磁盘上，而这一步在不同发行版上难度差很多。

apt 系走多架构机制，相对省事：

# 启用 i386 架构，更新索引后安装 32 位开发包 sudo dpkg --add-architecture i386 sudo apt-get update sudo apt-get install -y libmysqlclient-dev:i386 # 安装 32 位编译所需的基础运行库和头文件 sudo apt-get install -y gcc-multilib g++-multilib # 验证 32 位库确实到位 ls -l /usr/lib/i386-linux-gnu/libmysqlclient*

rpm 系对 32 位开发包的支持参差不齐，很多仓库里只有.i686的运行时包、没有对应的devel包，dnf install mysql-devel.i686直接报没有可用包是常事。这种情况就别在包管理器上耗时间了，拿一份客户端库源码，用 32 位工具链单独编一份，装到独立前缀：

# 用 32 位工具链单独构建客户端库，装到独立前缀，避免污染系统目录 mkdir -p build32 && cd build32 cmake .. \ -DCMAKE_INSTALL_PREFIX=/opt/mysql-client32 \ -DCMAKE_C_FLAGS="-m32" \ -DCMAKE_CXX_FLAGS="-m32" \ -DCMAKE_EXE_LINKER_FLAGS="-m32" \ -DWITH_SSL=system make -j"$(nproc)" && sudo make install

这里几个参数的作用要清楚：CMAKE_C_FLAGS=-m32让编译产出的目标文件是 32 位；CMAKE_EXE_LINKER_FLAGS=-m32保证构建过程中链接出来的中间工具也是 32 位，否则 CMake 在配置阶段就会因为「编译出的测试程序跑不起来」而失败；CMAKE_INSTALL_PREFIX单独指定前缀，是为了和系统自带的 64 位版本彻底隔离，避免后面-L指错目录。这套流程跑通一次之后，把它写进构建脚本，换机器照抄就行。

3.3 用 mysql_config 和 ldconfig 反查真实路径

库装好了，下一步是把路径问出来，而不是背下来。mysql_config是随开发包一起装的脚本，能把编译和链接需要的参数原样吐给你：

# 确认当前用的是哪个 mysql_config，多版本共存时这行很关键 which -a mysql_config # 逐项输出：版本、头文件目录、编译参数、链接参数 mysql_config --version mysql_config --include # 等价于 -I 那部分 mysql_config --cflags # 完整编译参数 mysql_config --libs # 完整链接参数 # 查看动态加载器的缓存里注册了哪些 mysqlclient ldconfig -p | grep mysqlclient

mysql_config --libs的输出往往不只有-lmysqlclient，还会带上-lssl -lcrypto -lz之类的依赖，这是因为客户端库本身依赖这些库，静态链接时尤其不能漏。ldconfig -p则是从运行时的角度看问题：只有注册进缓存的库，动态加载器才认，手工make install到/opt下的库默认不在缓存里，这就是后面「编译过了、跑起来找不到 so」的根源。

注意：机器上同时存在系统包和自行编译的客户端时，which -a mysql_config会返回多条路径。构建脚本里要么写绝对路径，要么在PATH里把想要的那份排前面，别指望默认顺序。

4. 编译链接参数：-I、-L、-l 的先后顺序和 CMake 写法

4.1 一个最小可复现的 C 例子

原理讲完，落到能跑的代码。下面这个程序只做三件事：初始化、连接、打印客户端版本，够用来验证头文件和库文件是否配平。

/* demo.c: 最小连接验证，重点在编译链接而非业务逻辑 */ #include <mysql/mysql.h> #include <stdio.h> int main(void) { MYSQL *conn = mysql_init(NULL); if (conn == NULL) { fprintf(stderr, "mysql_init failed\n"); return 1; } /* 参数依次为：句柄、主机、用户、密码、库名、端口、socket、客户端flag */ if (mysql_real_connect(conn, "127.0.0.1", "demo", "demo", "demo", 3306, NULL, 0) == NULL) { fprintf(stderr, "connect failed: %s\n", mysql_error(conn)); mysql_close(conn); return 2; } /* 客户端库版本，用来确认链接到的到底是哪一份库 */ printf("client version: %s\n", mysql_get_client_info()); mysql_close(conn); return 0; }

编译命令有两种写法，先看最省事的一种：

# 用 mysql_config 吐出的参数直接拼命令，适合本机快速验证 gcc -o demo demo.c $(mysql_config --cflags) $(mysql_config --libs)

把它展开，等价于下面这种手写形式，也是交叉编译时必须用的形式：

# 64 位：-I 指定头文件所在目录，-L 指定库目录，-l 指定库名 gcc -m64 -I/usr/include/mysql -o demo demo.c \ -L/usr/lib64/mysql -lmysqlclient # 32 位：除了 -m32，-L 也必须换成 32 位目录 gcc -m32 -I/usr/include/mysql -o demo32 demo.c \ -L/usr/lib/i386-linux-gnu -lmysqlclient

参数说明值得逐条过一遍。-I/usr/include/mysql是因为代码里写的是#include <mysql/mysql.h>——如果你的-I已经指到了/usr/include/mysql，代码里就得写#include <mysql.h>，两者必须匹配，这是后面避坑章节里的一条。-L指定目录，-l只写名字去掉lib前缀和扩展名。-m32影响的是编译和链接两端，编译器会自动切换到 32 位的系统头搜索路径，但不会自动帮你把-L换成 32 位目录，这一步必须手写。

另外注意-lmysqlclient的位置：它必须写在源文件或目标文件之后。链接器是从左到右扫描的，先看到符号引用、后看到库，才能把符号补上；反过来写就会出现「库明明在，却报 undefined reference」的玄学现象。

4.2 静态链接要多补一串依赖

动态链接是默认行为，-lmysqlclient优先命中.so。真要做静态链接，两个问题必须一起解决：一是强制链接器走静态库，二是把客户端库自己依赖的库补全。

# 强制静态链接 mysqlclient，其余依赖仍走动态库 gcc -m64 -I/usr/include/mysql -o demo demo.c \ -L/usr/lib64/mysql \ -Wl,-Bstatic -lmysqlclient -Wl,-Bdynamic \ -lssl -lcrypto -lz -ldl -lpthread -lm

-Wl,-Bstatic和-Wl,-Bdynamic是一对开关，夹在中间的-lmysqlclient走静态，后面的 ssl、crypto、z 又切回动态，这样既拿到静态的客户端库，又不用把整条依赖链都静态化。漏掉-lssl -lcrypto的后果是链接期报一堆undefined reference to SSL_xxx，看着像 MySQL 的问题，其实是 OpenSSL 的符号没补。-ldl、-lpthread、-lm同理，属于静态链接时的常见补齐项。

还有一点常被忽略：静态链接后，mysql_get_client_info()返回的版本来自编译期链接进去的那份.a，而不是运行环境里的.so。出问题时先打印这一行，能立刻排除「运行时加载错了库」这条怀疑链。

4.3 CMake 里不写死路径的写法

手写-L的问题是换台机器就得改。CMake 里比较稳的做法是自己找路径，而不是依赖某个可能不存在的 Find 模块。

# 先找头文件，PATH_SUFFIXES 覆盖 mysql 和兼容实现的目录名 find_path(MYSQL_INCLUDE_DIR NAMES mysql.h PATH_SUFFIXES mysql mariadb ) # 再找库，NAMES 里同时给带 lib 前缀和不带前缀两种写法 find_library(MYSQL_LIBRARY NAMES mysqlclient libmysqlclient PATH_SUFFIXES mysql ) if(NOT MYSQL_INCLUDE_DIR OR NOT MYSQL_LIBRARY) message(FATAL_ERROR "mysql client not found, check devel package") endif() target_include_directories(app PRIVATE ${MYSQL_INCLUDE_DIR}) target_link_libraries(app PRIVATE ${MYSQL_LIBRARY})

find_path和find_library会走 CMake 自己的搜索规则，覆盖系统目录和常见的多架构目录，跨发行版时比硬编码稳妥。PATH_SUFFIXES是为了处理头文件被放进mysql/子目录的情况。如果发行版提供了 pkg-config 文件，也可以先试这条路：

find_package(PkgConfig REQUIRED) pkg_check_modules(MYSQL REQUIRED mysqlclient) target_include_directories(app PRIVATE ${MYSQL_INCLUDE_DIRS}) target_link_libraries(app PRIVATE ${MYSQL_LIBRARIES})

能不能用取决于打包方有没有提供.pc文件，所以常见做法是 pkg-config 优先、find_path/find_library兜底，两条路都留。至于 32 位构建，CMake 侧不要试图用变量硬改，直接在配置阶段传工具链参数最干净：cmake -DCMAKE_C_FLAGS=-m32 -DCMAKE_EXE_LINKER_FLAGS=-m32 ..，同时在find_library之前把CMAKE_PREFIX_PATH指到 32 位那份前缀上，否则找到的还是 64 位库。

5. 避坑与排查：五个让链接器翻车的典型现场

5.1 报 skipping incompatible 却提示 cannot find

现象：gcc -m32编译时，日志里先出现一行skipping incompatible /usr/lib64/mysql/libmysqlclient.so，最后以cannot find -lmysqlclient结束。

原因：-L指到了 64 位目录，链接器发现文件位数不匹配就跳过，跳完整个目录没找到可用的，于是报「找不到」。它没有说谎，只是没说全部。

解决：把-L换成 32 位目录，先用gcc -m32 -print-file-name=libmysqlclient.so确认能解析到绝对路径，再编译。如果返回的还是裸文件名，说明 32 位库根本没装，回到 3.2 节。

5.2 编译通过，运行时提示 cannot open shared object file

现象：./demo一跑就报error while loading shared libraries: libmysqlclient.so.xx: cannot open shared object file。

原因：链接期找到了库，但运行时动态加载器找不到。手工装到/opt下的库不在ld.so.cache里，编译期给过-L对它没有任何约束力。

解决：三选一。写进系统配置最稳，echo /opt/mysql-client/lib > /etc/ld.so.conf.d/mysql-client.conf && ldconfig；不想动系统配置就用-Wl,-rpath,/opt/mysql-client/lib把路径烧进可执行文件；临时调试可以用LD_LIBRARY_PATH，但别把它写进启动脚本，环境变量污染比想象中难查。

5.3 库找到了却报 undefined reference

现象：-lmysqlclient明明在，ldd也能看到依赖，编译时还是一堆undefined reference to mysql_init。

原因：九成是参数顺序问题——-lmysqlclient写在了demo.c前面，链接器扫到库的时候还没有任何符号引用，扫完就丢弃了。剩下一成是--as-needed把库裁掉了。

解决：把-l挪到源文件后面；确认无效时加-Wl,--no-as-needed再试一次。顺便检查有没有误写成老的-lmysqlclient_r，那个库在新版本里已经合并或移除，写了也白写。

5.4 头文件找到了，编译还是报子头文件缺失

现象：-I/usr/include加上了，mysql.h能打开，但编译报mysql_version.h: No such file or directory。

原因：-I指到了上一级，而库自带的头文件之间用的是同级引用，/usr/include/mysql里的文件互相找得到，/usr/include里找不到。

解决：-I精确指到/usr/include/mysql，同时把代码里的 include 写法统一成#include <mysql.h>；或者保留-I/usr/include不动，代码里写#include <mysql/mysql.h>。两种风格只能选一种，混用必炸。

5.5 机器上有两份客户端，运行期加载错了

现象：编译一切正常，运行时报认证插件相关的错误，或者打印出来的客户端版本和预期不一致。

原因：系统包和自行编译的版本同时存在，soname 相同，动态加载器按缓存顺序挑了先注册的那份。老版本客户端库连新版本服务端时，认证方式对不上就会在这一步暴露。

解决：ldd ./demo | grep mysqlclient看实际加载路径，用-Wl,-rpath固定到想要的那份，并清理掉ld.so.conf.d里多余的条目。规范做法是同一种客户端库在一台机器上只留一份系统级安装，其余全部走独立前缀加 rpath。

6. 进阶：多版本共存下的 32 位构建验证

多版本共存这件事，靠「装完就算了」迟早出事。我现在的习惯是给每个版本一个独立前缀，命名里带版本和位数，构建脚本里只引用绝对路径，系统目录一概不碰：

这张表的核心思路是把「编译期、链接期、运行期」三个阶段的结论分别固化下来，而不是等程序跑挂了再回头一项项猜。前两项在装完环境时跑一次，后三项每次改构建脚本时跑一次，成本很低。

还有一个具体技巧：把库路径通过 rpath 烧进产物，同时保留一份可覆盖的开关。写法是-Wl,-rpath,/opt/mysql-client32/lib -Wl,--enable-new-dtags，新版链接器会生成RUNPATH而不是RPATH，好处是LD_LIBRARY_PATH仍然可以覆盖它——调试时能临时换库，发布时又不依赖环境变量。这个差别用readelf -d ./demo32 | grep -E 'RPATH|RUNPATH'就能看出来，是排查「为什么我设了环境变量却没生效」的关键线索。

32 位构建最容易忽略的一步是验证工具链本身。先编一个不依赖任何第三方库的空程序跑通-m32，再往里加 MySQL，能把「工具链缺 32 位运行库」和「MySQL 库位数不对」两类问题彻底分开。我吃过一次亏：花了两小时排查-lmysqlclient找不到，最后发现是gcc-multilib压根没装，链接器连 32 位的启动文件都没有。从那以后我每接一个要连库的构建，都先把 include 和 lib 的绝对路径打印出来贴进构建脚本注释里，再跑一遍ldd确认，两步做完才动手写业务代码。希望帮到你。

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