简介面向在 Linux 环境下进行 C/C 开发、需要连接 MySQL 数据库的开发者这份资源提供编译期所需的头文件与链接库免去安装 mysql-devel 或部署完整客户端与服务端的麻烦。压缩包共 77 个文件以 68 个 .h 头文件、8 个 .a 静态库和 1 个 .so 动态库为主头文件用于声明 MySQL C API 接口库文件供链接 mysqlclient 使用整体约 16.49MB并同时提供 32 位与 64 位两套目录可按系统架构直接取用。使用时将头文件与库目录放到工程同级路径在 Makefile 中通过 -I 与 -L 指定即可完成编译链接适合快速搭建本地数据库访问环境或移植既有工程。目前已有 1143 人学习下载对需要离线编译、避免依赖系统包管理器的场景较为实用。1. 编译报错先别急着改代码Linux 下连 MySQL 的头文件和库文件到底缺在哪上周帮一位开发者看一台编译机代码里就一行#include mysql.hgcc直接甩出fatal error: mysql.h: No such file or directory。他以为是 MySQL 没装systemctl status mysqld一看服务跑得好好的于是开始怀疑人生。这个场景太常见了服务端装好了不等于开发用的头文件和库文件就位。Linux 发行版把 MySQL 拆成运行时包和开发包两套mysql-server、mysql-client只给你可执行程序和共享库mysql.h、libmysqlclient.so这些编译期要用的东西在libmysqlclient-devDebian/Ubuntu或mysql-develRHEL/CentOS里。更麻烦的是 32 位和 64 位两套库经常同时存在链接器默认只认其中一套-lmysqlclient到底链到谁全看你有没有把路径和-L顺序写对。这篇笔记就按我实际装机的顺序把版本选择、开发包安装、头文件与库文件定位、32/64 位区分、编译验证和翻车救援一次讲清适合刚在 Linux 上写 C/C 连库的新手也适合被undefined reference折磨过的熟手对照排查。2. 装之前先把环境盘清楚发行版、位数与 MySQL 版本三件事动手装包之前先把三件事确认掉否则后面全是玄学。第一是发行版和包管理器Debian 系用aptRHEL 系用yum/dnf两边的包名完全不同混着抄命令必翻车。第二是目标程序的位数你要编 64 位程序就得有 64 位开发库要编 32 位程序就得额外装 32 位开发库很多机器只装了 64 位的。第三是 MySQL 的版本线5.7、8.0、8.4 的头文件路径和默认认证插件都有差异客户端库的 ABI 也不是完全兼容编译时链接的库版本最好和服务端大版本对齐。2.1 确认发行版、架构和已装的 MySQL 组件先跑几条只读命令把现状摸清别急着apt install。下面这组命令我每次上陌生机器都会先执行一遍输出记下来后面排错时能省很多时间。# 看发行版和版本号决定后面用 apt 还是 dnf cat /etc/os-release # 看内核架构x86_64 表示系统主体是 64 位 uname -m # 看已安装的 mysql 相关包确认服务端/客户端在不在 # Debian/Ubuntu dpkg -l | grep -i mysql # RHEL/CentOS/Rocky rpm -qa | grep -i mysql # 看 mysql_config 是否存在它是开发包自带的编译参数查询工具 which mysql_config || echo mysql_config 未安装uname -m输出x86_64只说明系统是 64 位不代表你没有 32 位需求如果项目要交付给 32 位环境后面必须单独装i386或i686的开发包。mysql_config是判断开发包是否装好的最快信号它不存在基本等于libmysqlclient-dev/mysql-devel没装。dpkg -l和rpm -qa的输出重点看有没有-dev或-devel结尾的包没有就是缺开发文件。2.2 版本选择客户端库跟服务端大版本对齐版本这块我的取舍很直接编译用的客户端库大版本尽量和服务端一致。服务端 8.0就装 8.0 的开发包服务端 5.7就装 5.7 的开发包。原因不是强迫症而是 8.0 默认认证插件换成了caching_sha2_password老版本客户端库连上去会报认证失败头文件里的一些结构体字段也有增减。发行版仓库里的开发包版本通常跟随系统自带 MySQL如果你服务端是单独装的官方包开发包也建议走同一来源避免头文件和.so版本错位。场景服务端版本建议开发包备注Ubuntu 22.04 默认源MySQL 8.0libmysqlclient-dev头文件在/usr/include/mysqlUbuntu 20.04 默认源MySQL 8.0libmysqlclient-dev同上注意 32 位需另装RHEL/CentOS 7MySQL 5.7 或 MariaDBmysql-devel或mariadb-devel两者头文件路径不同官方二进制包安装8.0/8.4对应版本-devel包路径常在/usr/local/mysql/include表里最后一行是重点用官方 tar 包或二进制安装的 MySQL头文件和库不在系统默认路径gcc找不到是正常的得手动加-I和-L。这一点后面 3.3 会展开。2.3 32 位与 64 位开发库的差别先讲透很多人卡在 32 位是因为不知道 Linux 上 32 位和 64 位库是两套独立文件不是一套库兼容两种。64 位库一般在/usr/lib/x86_64-linux-gnu/Debian 系或/usr/lib64/RHEL 系32 位库在/usr/lib/i386-linux-gnu/或/usr/lib/。libmysqlclient.so这个软链接指向哪个版本取决于你装的是哪个架构的包。编译 32 位程序时gcc -m32会去 32 位库目录找找不到就报cannot find -lmysqlclient反过来编 64 位程序却链到了 32 位库会报file in wrong format。这两个报错含义完全不同别混为一谈。提示先明确你的交付目标位数再决定装哪套开发包。两边都要就两套都装不要指望一套库通吃。3. 安装开发包apt 与 dnf 两条路外加手动指定路径环境盘清之后进入安装。这一章按包管理器分两条路走再补一条官方二进制包的手动路径最后讲怎么确认头文件和库文件真的到位。每一步都给命令和参数说明照着敲之前先看清注释。3.1 Debian/Ubuntu 下装 libmysqlclient-devDebian 系最省事一条命令搞定 64 位开发环境。装之前先apt update否则可能拿到旧索引导致包找不到。# 更新包索引 sudo apt update # 安装 MySQL 客户端开发包包含 mysql.h 和 libmysqlclient.so sudo apt install -y libmysqlclient-dev # 如果系统里是 MariaDB 替代品包名可能是 libmariadb-dev # sudo apt install -y libmariadb-dev # 验证头文件位置 dpkg -L libmysqlclient-dev | grep -E mysql\.h|libmysqlclient\.solibmysqlclient-dev会拉入libmysqlclient20或libmysqlclient21作为依赖具体版本跟随发行版。dpkg -L列出包内所有文件用grep过滤出头文件和库文件的实际路径这一步比盲目猜路径靠谱。如果输出里mysql.h在/usr/include/mysql/mysql.h说明代码里应该写#include mysql/mysql.h或者编译时加-I/usr/include/mysql再写#include mysql.h两种写法选一种别混。32 位开发包在 64 位 Ubuntu 上需要先开多架构支持再装i386版本# 开启 i386 架构支持只需执行一次 sudo dpkg --add-architecture i386 sudo apt update # 安装 32 位开发包 sudo apt install -y libmysqlclient-dev:i386 # 确认 32 位库文件存在 ls -l /usr/lib/i386-linux-gnu/libmysqlclient.so*--add-architecture i386是让apt认识 32 位包的前提不加这步直接装:i386会报找不到包。装完后 32 位库落在/usr/lib/i386-linux-gnu/编译时gcc -m32会自动去这个目录找一般不用额外加-L。如果同时装了 64 位和 32 位libmysqlclient.so软链接在两个目录各有一份互不干扰。3.2 RHEL/CentOS/Rocky 下装 mysql-develRHEL 系包名是mysql-devel如果系统用的是 MariaDB 替代则是mariadb-devel。CentOS 7 之后默认源里 MySQL 相关包有变化先确认源里有没有再装。# 搜索可用的开发包确认包名 yum search mysql-devel # 或 dnf search mysql-devel # 安装开发包 sudo yum install -y mysql-devel # Rocky/Alma 用 dnf # sudo dnf install -y mysql-devel # 验证头文件和库 rpm -ql mysql-devel | grep -E mysql\.h|libmysqlclient\.soyum search先确认包名是因为部分系统源里只有mariadb-devel直接装mysql-devel会提示无可用包。rpm -ql的作用和dpkg -L一样列出包内文件路径。RHEL 系 64 位库通常在/usr/lib64/mysql/头文件在/usr/include/mysql/编译时如果gcc找不到加-I/usr/include/mysql -L/usr/lib64/mysql即可。32 位在 RHEL 系上要装i686版本包名带架构后缀# 安装 32 位开发包 sudo yum install -y mysql-devel.i686 # 确认 32 位库 ls -l /usr/lib/mysql/libmysqlclient.so*mysql-devel.i686这个写法是 yum 指定架构的标准方式装完后 32 位库在/usr/lib/mysql/。注意 RHEL 系 32 位和 64 位库目录不同-m32编译时链接器会优先找 32 位目录但如果你手动加了-L/usr/lib64/mysql就会把 64 位库塞给 32 位链接器直接报格式错误。这个坑在 5.2 会细说。3.3 官方二进制包场景手动指定 include 和 lib 路径用官方 tar 包或二进制安装的 MySQL开发文件不在系统路径apt/yum装的开发包版本也可能对不上。这种情况我一般直接用安装目录下的头文件和库编译命令里显式指定路径。# 假设 MySQL 装在 /usr/local/mysql # 确认头文件和库存在 ls /usr/local/mysql/include/mysql.h ls /usr/local/mysql/lib/libmysqlclient.so* # 编译时显式指定头文件目录和库目录 gcc main.c -o main \ -I/usr/local/mysql/include \ -L/usr/local/mysql/lib \ -lmysqlclient # 运行时如果提示找不到 .so把库目录加进加载路径 export LD_LIBRARY_PATH/usr/local/mysql/lib:$LD_LIBRARY_PATH-I告诉编译器去哪找#include的头文件-L告诉链接器去哪找-l指定的库-lmysqlclient是链接libmysqlclient.so的简写。三个参数顺序有讲究-I放源文件前后都行-L和-l必须放在源文件之后否则老版本gcc会报undefined reference。LD_LIBRARY_PATH只影响运行时动态库查找编译期不生效别拿它当编译参数用。更稳妥的做法是写进/etc/ld.so.conf.d/再ldconfig这个在 6.1 验证时会讲。3.4 用 mysql_config 一次性拿到正确编译参数手动拼-I和-L容易漏开发包自带的mysql_config能直接吐出编译和链接参数这是我最推荐的方式尤其适合写进 Makefile。# 查看编译参数头文件路径 mysql_config --cflags # 查看链接参数库路径和库名 mysql_config --libs # 直接用在编译命令里 gcc main.c -o main $(mysql_config --cflags) $(mysql_config --libs)--cflags输出类似-I/usr/include/mysql -DMYSQL_DYNAMIC_PLUGIN这样的内容--libs输出-L/usr/lib/x86_64-linux-gnu -lmysqlclient。用$()把命令输出嵌进编译命令路径随环境自动变换机器不用改 Makefile。注意mysql_config本身也分 32/64 位如果你装了两套开发包which mysql_config看它指向哪个必要时用绝对路径指定对应架构的那份。4. 头文件与库文件的定位逻辑编译器到底去哪找装完包不等于编译就能过得知道编译器找文件的顺序出问题才知道往哪查。这一章讲头文件搜索路径、库文件搜索路径以及 32/64 位下路径怎么区分属于配置原理部分看懂了后面排错就是体力活。4.1 头文件搜索顺序与 -I 的插入位置gcc找#include xxx.h的顺序是-I指定目录 → 系统默认 include 目录/usr/include、/usr/local/include等→ 编译器内置目录。#include xxx.h则先找源文件所在目录再走上面的顺序。所以mysql.h在/usr/include/mysql/下时写#include mysql.h找不到写#include mysql/mysql.h能找到或者加-I/usr/include/mysql后写mysql.h也能找到。# 查看 gcc 默认的头文件搜索路径 echo | gcc -E -Wp,-v - 21 | grep -A20 search starts here # 查看加了 -I 之后的搜索顺序变化 echo | gcc -E -Wp,-v -I/usr/include/mysql - 21 | grep -A20 search starts here-E只做预处理-Wp,-v把预处理器的详细搜索路径打出来echo |给一个空输入避免报错。对比两条命令的输出能看到-I目录被插到了系统目录前面。这个技巧在头文件版本冲突时特别有用系统里装了两份mysql.h-I顺序决定用哪份把想要的放前面就行。4.2 库文件搜索顺序与 -L、-l 的配合链接器找库的顺序是-L指定目录 → 环境变量LIBRARY_PATH→ 系统默认库目录/usr/lib、/usr/lib64、/usr/local/lib等。-lmysqlclient会被展开成libmysqlclient.so或libmysqlclient.a优先找动态库。这里有个容易忽略的点-L的顺序决定同名库的优先级多个目录都有libmysqlclient.so时排前面的赢。# 查看链接器默认搜索的库目录 ld --verbose | grep SEARCH_DIR # 查看某个库实际链到了哪个文件 ldd ./main | grep mysql # 查看库文件是 32 位还是 64 位 file /usr/lib/x86_64-linux-gnu/libmysqlclient.so file /usr/lib/i386-linux-gnu/libmysqlclient.sold --verbose | grep SEARCH_DIR输出链接器内置搜索目录能确认系统默认去哪找。ldd看的是运行时实际加载的库编译过了但运行报错时用它。file命令直接告诉你库的位数ELF 64-bit和ELF 32-bit一目了然比猜目录可靠。我一般编译完先跑一遍file和ldd确认链对了再往下走。4.3 32 位与 64 位库目录对照不同发行版的 32/64 位库目录不统一这张表建议存下来排错时直接对号入座。发行版系64 位库目录32 位库目录头文件目录Debian/Ubuntu/usr/lib/x86_64-linux-gnu//usr/lib/i386-linux-gnu//usr/include/mysql/RHEL/CentOS 7/usr/lib64/mysql//usr/lib/mysql//usr/include/mysql/官方二进制包/usr/local/mysql/lib/同目录下按版本区分/usr/local/mysql/include/Debian 系的多架构目录命名很规整x86_64-linux-gnu和i386-linux-gnu一眼能分。RHEL 系 64 位在lib6432 位在lib注意别把lib当成通用目录。官方二进制包通常只提供一种架构32 位需要单独下载对应包目录结构以实际解压为准。注意/usr/lib在部分 64 位系统上是/usr/lib64的软链接ls -l /usr/lib先看清楚再判断别被表象骗了。5. 避坑与排查五条血泪记录每条都能对上号这一章是我这些年踩过的坑里挑出来的五条现象、原因、解决都写清楚遇到同类报错直接对照。顺序按出现频率排第一条几乎人人都会撞上。5.1 现象fatal error: mysql.h: No such file or directory原因开发包没装或者装了但头文件在子目录代码里写的是mysql.h而不是mysql/mysql.h编译命令也没加-I。解决先dpkg -L libmysqlclient-dev | grep mysql.h或rpm -ql mysql-devel | grep mysql.h确认头文件在不在。在的话看路径是/usr/include/mysql/mysql.h就改 include 写法或加-I/usr/include/mysql不在就装开发包。还有一种情况是装了 MariaDB 的开发包头文件叫mysql.h但路径在/usr/include/mariadb/同样加-I解决。5.2 现象cannot find -lmysqlclient或file in wrong format原因前者是链接器在搜索路径里找不到libmysqlclient.so常见于只装了运行时包没装开发包或者 32 位编译但只装了 64 位库。后者是位数不匹配32 位链接器拿到了 64 位库或反过来。解决cannot find先用find / -name libmysqlclient.so* 2/dev/null定位库在哪在的话加-L指过去找不到就补装开发包。wrong format用file看库的位数和gcc -m32/-m64对齐。特别注意手动加-L/usr/lib64/mysql去编 32 位程序这是最常见的自伤操作把-L换成 32 位目录即可。5.3 现象编译通过运行报error while loading shared libraries: libmysqlclient.so.21原因编译期找到了库运行时动态加载器找不到。-L只影响链接期不影响运行期两者是两套搜索机制。解决三个办法选一个。临时用export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH永久写进/etc/ld.so.conf.d/mysql.conf再sudo ldconfig或者编译时加-Wl,-rpath,/usr/lib/x86_64-linux-gnu把路径烧进可执行文件。生产环境我倾向第二种统一管理交付单个程序用第三种不依赖环境变量。5.4 现象链接时报一堆undefined reference to mysql_xxx原因-lmysqlclient放的位置不对放在了源文件前面。链接器从左到右处理先遇到-l时还没有未解析符号等处理到源文件产生的符号时库已经扫过了不会回头再找。解决把-lmysqlclient挪到源文件或目标文件之后。用mysql_config --libs生成参数时天然在正确位置手写命令容易犯这个错。另外 C 项目要注意extern C包裹否则符号名被 mangle同样报 undefined reference。5.5 现象32 位和 64 位库都装了编译结果却链错版本原因libmysqlclient.so软链接指向不确定或者-L顺序把错误目录排前面或者mysql_config指向了另一套架构。解决ls -l看软链接指向file确认目标文件位数which mysql_config和mysql_config --libs看它吐出的路径属于哪套。编译命令里显式写-L到目标架构目录并且放在其他-L前面。最稳的办法是两套环境分开32 位编译用独立的构建目录和显式路径不依赖系统默认。6. 装完怎么验证跑通一个最小连接程序加三步检查装完包、配好路径最后一步是验证。我习惯写一个最小连接程序能编过、能跑通、能查到数据三关都过才算这套环境真的可用。下面这个例子用 C 写只做连接和版本查询不涉及业务逻辑方便快速定位问题。/* mysql_check.c - 最小连接验证程序 */ #include stdio.h #include mysql/mysql.h /* 头文件在子目录时这样写或加 -I 后写 mysql.h */ int main(void) { MYSQL *conn; MYSQL_RES *res; MYSQL_ROW row; /* 初始化客户端库 */ conn mysql_init(NULL); if (conn NULL) { fprintf(stderr, mysql_init failed\n); return 1; } /* 连接数据库主机、用户、密码、库名、端口、socket、标志 */ if (mysql_real_connect(conn, 127.0.0.1, testuser, testpass, testdb, 3306, NULL, 0) NULL) { fprintf(stderr, connect failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } /* 查询客户端库版本验证链路通 */ if (mysql_query(conn, SELECT VERSION()) ! 0) { fprintf(stderr, query failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } res mysql_store_result(conn); if (res NULL) { fprintf(stderr, store_result failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } row mysql_fetch_row(res); if (row ! NULL) { printf(mysql client version: %s\n, row[0]); } mysql_free_result(res); mysql_close(conn); return 0; }mysql_init分配并初始化连接句柄失败一般是内存问题。mysql_real_connect的七个参数依次是句柄、主机、用户、密码、库名、端口、socket 路径、客户端标志socket 传NULL表示走 TCP标志传 0 用默认。mysql_query返回非 0 表示 SQL 执行失败用mysql_error取原因。mysql_store_result把结果集拉到客户端用完必须mysql_free_result释放否则内存泄漏。这段代码故意把错误信息打全就是为了验证阶段能一眼看出卡在哪一步。编译和运行分两条命令注意参数顺序# 编译源文件在前库参数在后 gcc mysql_check.c -o mysql_check $(mysql_config --cflags) $(mysql_config --libs) # 运行前确认库路径必要时设置 ./mysql_check # 如果运行报找不到 .so用 ldd 确认实际加载路径 ldd ./mysql_check | grep mysql编译命令里$(mysql_config --cflags)和$(mysql_config --libs)分别展开成头文件参数和链接参数源文件mysql_check.c必须放在--libs展开的-l之前这是 5.4 那条坑的直接应用。运行后输出mysql client version: 8.0.xx说明连接和查询都通了。如果ldd显示not found回到 5.3 处理动态库路径。三步检查我一般按这个顺序走第一步file ./mysql_check确认可执行文件位数和预期一致第二步ldd ./mysql_check | grep mysql确认链到的是目标架构的库且路径存在第三步才是运行程序看输出。前两步过了第三步基本不会出问题反过来直接运行报错再去查往往要多绕几圈。32 位验证同理编译时加-m32file输出应为ELF 32-bitldd里库路径应指向 32 位目录。从那以后我每次在新机器上配 MySQL 开发环境都强制先跑一遍mysql_config --cflags --libs和这个最小连接程序确认头文件、库文件、运行时加载三关全过再动业务代码。这套习惯帮我省掉了大量「代码明明没问题却编不过」的排查时间。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/27 10:57:06 · 阅读 1.2k Linux下C/C++连接MySQL：头文件与库文件缺失的编译链接排查指南
简介面向在 Linux 环境下进行 C/C 开发、需要连接 MySQL 数据库的开发者这份资源提供编译期所需的头文件与链接库免去安装 mysql-devel 或部署完整客户端与服务端的麻烦。压缩包共 77 个文件以 68 个 .h 头文件、8 个 .a 静态库和 1 个 .so 动态库为主头文件用于声明 MySQL C API 接口库文件供链接 mysqlclient 使用整体约 16.49MB并同时提供 32 位与 64 位两套目录可按系统架构直接取用。使用时将头文件与库目录放到工程同级路径在 Makefile 中通过 -I 与 -L 指定即可完成编译链接适合快速搭建本地数据库访问环境或移植既有工程。目前已有 1143 人学习下载对需要离线编译、避免依赖系统包管理器的场景较为实用。1. 编译报错先别急着改代码Linux 下连 MySQL 的头文件和库文件到底缺在哪上周帮一位开发者看一台编译机代码里就一行#include mysql.hgcc直接甩出fatal error: mysql.h: No such file or directory。他以为是 MySQL 没装systemctl status mysqld一看服务跑得好好的于是开始怀疑人生。这个场景太常见了服务端装好了不等于开发用的头文件和库文件就位。Linux 发行版把 MySQL 拆成运行时包和开发包两套mysql-server、mysql-client只给你可执行程序和共享库mysql.h、libmysqlclient.so这些编译期要用的东西在libmysqlclient-devDebian/Ubuntu或mysql-develRHEL/CentOS里。更麻烦的是 32 位和 64 位两套库经常同时存在链接器默认只认其中一套-lmysqlclient到底链到谁全看你有没有把路径和-L顺序写对。这篇笔记就按我实际装机的顺序把版本选择、开发包安装、头文件与库文件定位、32/64 位区分、编译验证和翻车救援一次讲清适合刚在 Linux 上写 C/C 连库的新手也适合被undefined reference折磨过的熟手对照排查。2. 装之前先把环境盘清楚发行版、位数与 MySQL 版本三件事动手装包之前先把三件事确认掉否则后面全是玄学。第一是发行版和包管理器Debian 系用aptRHEL 系用yum/dnf两边的包名完全不同混着抄命令必翻车。第二是目标程序的位数你要编 64 位程序就得有 64 位开发库要编 32 位程序就得额外装 32 位开发库很多机器只装了 64 位的。第三是 MySQL 的版本线5.7、8.0、8.4 的头文件路径和默认认证插件都有差异客户端库的 ABI 也不是完全兼容编译时链接的库版本最好和服务端大版本对齐。2.1 确认发行版、架构和已装的 MySQL 组件先跑几条只读命令把现状摸清别急着apt install。下面这组命令我每次上陌生机器都会先执行一遍输出记下来后面排错时能省很多时间。# 看发行版和版本号决定后面用 apt 还是 dnf cat /etc/os-release # 看内核架构x86_64 表示系统主体是 64 位 uname -m # 看已安装的 mysql 相关包确认服务端/客户端在不在 # Debian/Ubuntu dpkg -l | grep -i mysql # RHEL/CentOS/Rocky rpm -qa | grep -i mysql # 看 mysql_config 是否存在它是开发包自带的编译参数查询工具 which mysql_config || echo mysql_config 未安装uname -m输出x86_64只说明系统是 64 位不代表你没有 32 位需求如果项目要交付给 32 位环境后面必须单独装i386或i686的开发包。mysql_config是判断开发包是否装好的最快信号它不存在基本等于libmysqlclient-dev/mysql-devel没装。dpkg -l和rpm -qa的输出重点看有没有-dev或-devel结尾的包没有就是缺开发文件。2.2 版本选择客户端库跟服务端大版本对齐版本这块我的取舍很直接编译用的客户端库大版本尽量和服务端一致。服务端 8.0就装 8.0 的开发包服务端 5.7就装 5.7 的开发包。原因不是强迫症而是 8.0 默认认证插件换成了caching_sha2_password老版本客户端库连上去会报认证失败头文件里的一些结构体字段也有增减。发行版仓库里的开发包版本通常跟随系统自带 MySQL如果你服务端是单独装的官方包开发包也建议走同一来源避免头文件和.so版本错位。场景服务端版本建议开发包备注Ubuntu 22.04 默认源MySQL 8.0libmysqlclient-dev头文件在/usr/include/mysqlUbuntu 20.04 默认源MySQL 8.0libmysqlclient-dev同上注意 32 位需另装RHEL/CentOS 7MySQL 5.7 或 MariaDBmysql-devel或mariadb-devel两者头文件路径不同官方二进制包安装8.0/8.4对应版本-devel包路径常在/usr/local/mysql/include表里最后一行是重点用官方 tar 包或二进制安装的 MySQL头文件和库不在系统默认路径gcc找不到是正常的得手动加-I和-L。这一点后面 3.3 会展开。2.3 32 位与 64 位开发库的差别先讲透很多人卡在 32 位是因为不知道 Linux 上 32 位和 64 位库是两套独立文件不是一套库兼容两种。64 位库一般在/usr/lib/x86_64-linux-gnu/Debian 系或/usr/lib64/RHEL 系32 位库在/usr/lib/i386-linux-gnu/或/usr/lib/。libmysqlclient.so这个软链接指向哪个版本取决于你装的是哪个架构的包。编译 32 位程序时gcc -m32会去 32 位库目录找找不到就报cannot find -lmysqlclient反过来编 64 位程序却链到了 32 位库会报file in wrong format。这两个报错含义完全不同别混为一谈。提示先明确你的交付目标位数再决定装哪套开发包。两边都要就两套都装不要指望一套库通吃。3. 安装开发包apt 与 dnf 两条路外加手动指定路径环境盘清之后进入安装。这一章按包管理器分两条路走再补一条官方二进制包的手动路径最后讲怎么确认头文件和库文件真的到位。每一步都给命令和参数说明照着敲之前先看清注释。3.1 Debian/Ubuntu 下装 libmysqlclient-devDebian 系最省事一条命令搞定 64 位开发环境。装之前先apt update否则可能拿到旧索引导致包找不到。# 更新包索引 sudo apt update # 安装 MySQL 客户端开发包包含 mysql.h 和 libmysqlclient.so sudo apt install -y libmysqlclient-dev # 如果系统里是 MariaDB 替代品包名可能是 libmariadb-dev # sudo apt install -y libmariadb-dev # 验证头文件位置 dpkg -L libmysqlclient-dev | grep -E mysql\.h|libmysqlclient\.solibmysqlclient-dev会拉入libmysqlclient20或libmysqlclient21作为依赖具体版本跟随发行版。dpkg -L列出包内所有文件用grep过滤出头文件和库文件的实际路径这一步比盲目猜路径靠谱。如果输出里mysql.h在/usr/include/mysql/mysql.h说明代码里应该写#include mysql/mysql.h或者编译时加-I/usr/include/mysql再写#include mysql.h两种写法选一种别混。32 位开发包在 64 位 Ubuntu 上需要先开多架构支持再装i386版本# 开启 i386 架构支持只需执行一次 sudo dpkg --add-architecture i386 sudo apt update # 安装 32 位开发包 sudo apt install -y libmysqlclient-dev:i386 # 确认 32 位库文件存在 ls -l /usr/lib/i386-linux-gnu/libmysqlclient.so*--add-architecture i386是让apt认识 32 位包的前提不加这步直接装:i386会报找不到包。装完后 32 位库落在/usr/lib/i386-linux-gnu/编译时gcc -m32会自动去这个目录找一般不用额外加-L。如果同时装了 64 位和 32 位libmysqlclient.so软链接在两个目录各有一份互不干扰。3.2 RHEL/CentOS/Rocky 下装 mysql-develRHEL 系包名是mysql-devel如果系统用的是 MariaDB 替代则是mariadb-devel。CentOS 7 之后默认源里 MySQL 相关包有变化先确认源里有没有再装。# 搜索可用的开发包确认包名 yum search mysql-devel # 或 dnf search mysql-devel # 安装开发包 sudo yum install -y mysql-devel # Rocky/Alma 用 dnf # sudo dnf install -y mysql-devel # 验证头文件和库 rpm -ql mysql-devel | grep -E mysql\.h|libmysqlclient\.soyum search先确认包名是因为部分系统源里只有mariadb-devel直接装mysql-devel会提示无可用包。rpm -ql的作用和dpkg -L一样列出包内文件路径。RHEL 系 64 位库通常在/usr/lib64/mysql/头文件在/usr/include/mysql/编译时如果gcc找不到加-I/usr/include/mysql -L/usr/lib64/mysql即可。32 位在 RHEL 系上要装i686版本包名带架构后缀# 安装 32 位开发包 sudo yum install -y mysql-devel.i686 # 确认 32 位库 ls -l /usr/lib/mysql/libmysqlclient.so*mysql-devel.i686这个写法是 yum 指定架构的标准方式装完后 32 位库在/usr/lib/mysql/。注意 RHEL 系 32 位和 64 位库目录不同-m32编译时链接器会优先找 32 位目录但如果你手动加了-L/usr/lib64/mysql就会把 64 位库塞给 32 位链接器直接报格式错误。这个坑在 5.2 会细说。3.3 官方二进制包场景手动指定 include 和 lib 路径用官方 tar 包或二进制安装的 MySQL开发文件不在系统路径apt/yum装的开发包版本也可能对不上。这种情况我一般直接用安装目录下的头文件和库编译命令里显式指定路径。# 假设 MySQL 装在 /usr/local/mysql # 确认头文件和库存在 ls /usr/local/mysql/include/mysql.h ls /usr/local/mysql/lib/libmysqlclient.so* # 编译时显式指定头文件目录和库目录 gcc main.c -o main \ -I/usr/local/mysql/include \ -L/usr/local/mysql/lib \ -lmysqlclient # 运行时如果提示找不到 .so把库目录加进加载路径 export LD_LIBRARY_PATH/usr/local/mysql/lib:$LD_LIBRARY_PATH-I告诉编译器去哪找#include的头文件-L告诉链接器去哪找-l指定的库-lmysqlclient是链接libmysqlclient.so的简写。三个参数顺序有讲究-I放源文件前后都行-L和-l必须放在源文件之后否则老版本gcc会报undefined reference。LD_LIBRARY_PATH只影响运行时动态库查找编译期不生效别拿它当编译参数用。更稳妥的做法是写进/etc/ld.so.conf.d/再ldconfig这个在 6.1 验证时会讲。3.4 用 mysql_config 一次性拿到正确编译参数手动拼-I和-L容易漏开发包自带的mysql_config能直接吐出编译和链接参数这是我最推荐的方式尤其适合写进 Makefile。# 查看编译参数头文件路径 mysql_config --cflags # 查看链接参数库路径和库名 mysql_config --libs # 直接用在编译命令里 gcc main.c -o main $(mysql_config --cflags) $(mysql_config --libs)--cflags输出类似-I/usr/include/mysql -DMYSQL_DYNAMIC_PLUGIN这样的内容--libs输出-L/usr/lib/x86_64-linux-gnu -lmysqlclient。用$()把命令输出嵌进编译命令路径随环境自动变换机器不用改 Makefile。注意mysql_config本身也分 32/64 位如果你装了两套开发包which mysql_config看它指向哪个必要时用绝对路径指定对应架构的那份。4. 头文件与库文件的定位逻辑编译器到底去哪找装完包不等于编译就能过得知道编译器找文件的顺序出问题才知道往哪查。这一章讲头文件搜索路径、库文件搜索路径以及 32/64 位下路径怎么区分属于配置原理部分看懂了后面排错就是体力活。4.1 头文件搜索顺序与 -I 的插入位置gcc找#include xxx.h的顺序是-I指定目录 → 系统默认 include 目录/usr/include、/usr/local/include等→ 编译器内置目录。#include xxx.h则先找源文件所在目录再走上面的顺序。所以mysql.h在/usr/include/mysql/下时写#include mysql.h找不到写#include mysql/mysql.h能找到或者加-I/usr/include/mysql后写mysql.h也能找到。# 查看 gcc 默认的头文件搜索路径 echo | gcc -E -Wp,-v - 21 | grep -A20 search starts here # 查看加了 -I 之后的搜索顺序变化 echo | gcc -E -Wp,-v -I/usr/include/mysql - 21 | grep -A20 search starts here-E只做预处理-Wp,-v把预处理器的详细搜索路径打出来echo |给一个空输入避免报错。对比两条命令的输出能看到-I目录被插到了系统目录前面。这个技巧在头文件版本冲突时特别有用系统里装了两份mysql.h-I顺序决定用哪份把想要的放前面就行。4.2 库文件搜索顺序与 -L、-l 的配合链接器找库的顺序是-L指定目录 → 环境变量LIBRARY_PATH→ 系统默认库目录/usr/lib、/usr/lib64、/usr/local/lib等。-lmysqlclient会被展开成libmysqlclient.so或libmysqlclient.a优先找动态库。这里有个容易忽略的点-L的顺序决定同名库的优先级多个目录都有libmysqlclient.so时排前面的赢。# 查看链接器默认搜索的库目录 ld --verbose | grep SEARCH_DIR # 查看某个库实际链到了哪个文件 ldd ./main | grep mysql # 查看库文件是 32 位还是 64 位 file /usr/lib/x86_64-linux-gnu/libmysqlclient.so file /usr/lib/i386-linux-gnu/libmysqlclient.sold --verbose | grep SEARCH_DIR输出链接器内置搜索目录能确认系统默认去哪找。ldd看的是运行时实际加载的库编译过了但运行报错时用它。file命令直接告诉你库的位数ELF 64-bit和ELF 32-bit一目了然比猜目录可靠。我一般编译完先跑一遍file和ldd确认链对了再往下走。4.3 32 位与 64 位库目录对照不同发行版的 32/64 位库目录不统一这张表建议存下来排错时直接对号入座。发行版系64 位库目录32 位库目录头文件目录Debian/Ubuntu/usr/lib/x86_64-linux-gnu//usr/lib/i386-linux-gnu//usr/include/mysql/RHEL/CentOS 7/usr/lib64/mysql//usr/lib/mysql//usr/include/mysql/官方二进制包/usr/local/mysql/lib/同目录下按版本区分/usr/local/mysql/include/Debian 系的多架构目录命名很规整x86_64-linux-gnu和i386-linux-gnu一眼能分。RHEL 系 64 位在lib6432 位在lib注意别把lib当成通用目录。官方二进制包通常只提供一种架构32 位需要单独下载对应包目录结构以实际解压为准。注意/usr/lib在部分 64 位系统上是/usr/lib64的软链接ls -l /usr/lib先看清楚再判断别被表象骗了。5. 避坑与排查五条血泪记录每条都能对上号这一章是我这些年踩过的坑里挑出来的五条现象、原因、解决都写清楚遇到同类报错直接对照。顺序按出现频率排第一条几乎人人都会撞上。5.1 现象fatal error: mysql.h: No such file or directory原因开发包没装或者装了但头文件在子目录代码里写的是mysql.h而不是mysql/mysql.h编译命令也没加-I。解决先dpkg -L libmysqlclient-dev | grep mysql.h或rpm -ql mysql-devel | grep mysql.h确认头文件在不在。在的话看路径是/usr/include/mysql/mysql.h就改 include 写法或加-I/usr/include/mysql不在就装开发包。还有一种情况是装了 MariaDB 的开发包头文件叫mysql.h但路径在/usr/include/mariadb/同样加-I解决。5.2 现象cannot find -lmysqlclient或file in wrong format原因前者是链接器在搜索路径里找不到libmysqlclient.so常见于只装了运行时包没装开发包或者 32 位编译但只装了 64 位库。后者是位数不匹配32 位链接器拿到了 64 位库或反过来。解决cannot find先用find / -name libmysqlclient.so* 2/dev/null定位库在哪在的话加-L指过去找不到就补装开发包。wrong format用file看库的位数和gcc -m32/-m64对齐。特别注意手动加-L/usr/lib64/mysql去编 32 位程序这是最常见的自伤操作把-L换成 32 位目录即可。5.3 现象编译通过运行报error while loading shared libraries: libmysqlclient.so.21原因编译期找到了库运行时动态加载器找不到。-L只影响链接期不影响运行期两者是两套搜索机制。解决三个办法选一个。临时用export LD_LIBRARY_PATH/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH永久写进/etc/ld.so.conf.d/mysql.conf再sudo ldconfig或者编译时加-Wl,-rpath,/usr/lib/x86_64-linux-gnu把路径烧进可执行文件。生产环境我倾向第二种统一管理交付单个程序用第三种不依赖环境变量。5.4 现象链接时报一堆undefined reference to mysql_xxx原因-lmysqlclient放的位置不对放在了源文件前面。链接器从左到右处理先遇到-l时还没有未解析符号等处理到源文件产生的符号时库已经扫过了不会回头再找。解决把-lmysqlclient挪到源文件或目标文件之后。用mysql_config --libs生成参数时天然在正确位置手写命令容易犯这个错。另外 C 项目要注意extern C包裹否则符号名被 mangle同样报 undefined reference。5.5 现象32 位和 64 位库都装了编译结果却链错版本原因libmysqlclient.so软链接指向不确定或者-L顺序把错误目录排前面或者mysql_config指向了另一套架构。解决ls -l看软链接指向file确认目标文件位数which mysql_config和mysql_config --libs看它吐出的路径属于哪套。编译命令里显式写-L到目标架构目录并且放在其他-L前面。最稳的办法是两套环境分开32 位编译用独立的构建目录和显式路径不依赖系统默认。6. 装完怎么验证跑通一个最小连接程序加三步检查装完包、配好路径最后一步是验证。我习惯写一个最小连接程序能编过、能跑通、能查到数据三关都过才算这套环境真的可用。下面这个例子用 C 写只做连接和版本查询不涉及业务逻辑方便快速定位问题。/* mysql_check.c - 最小连接验证程序 */ #include stdio.h #include mysql/mysql.h /* 头文件在子目录时这样写或加 -I 后写 mysql.h */ int main(void) { MYSQL *conn; MYSQL_RES *res; MYSQL_ROW row; /* 初始化客户端库 */ conn mysql_init(NULL); if (conn NULL) { fprintf(stderr, mysql_init failed\n); return 1; } /* 连接数据库主机、用户、密码、库名、端口、socket、标志 */ if (mysql_real_connect(conn, 127.0.0.1, testuser, testpass, testdb, 3306, NULL, 0) NULL) { fprintf(stderr, connect failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } /* 查询客户端库版本验证链路通 */ if (mysql_query(conn, SELECT VERSION()) ! 0) { fprintf(stderr, query failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } res mysql_store_result(conn); if (res NULL) { fprintf(stderr, store_result failed: %s\n, mysql_error(conn)); mysql_close(conn); return 1; } row mysql_fetch_row(res); if (row ! NULL) { printf(mysql client version: %s\n, row[0]); } mysql_free_result(res); mysql_close(conn); return 0; }mysql_init分配并初始化连接句柄失败一般是内存问题。mysql_real_connect的七个参数依次是句柄、主机、用户、密码、库名、端口、socket 路径、客户端标志socket 传NULL表示走 TCP标志传 0 用默认。mysql_query返回非 0 表示 SQL 执行失败用mysql_error取原因。mysql_store_result把结果集拉到客户端用完必须mysql_free_result释放否则内存泄漏。这段代码故意把错误信息打全就是为了验证阶段能一眼看出卡在哪一步。编译和运行分两条命令注意参数顺序# 编译源文件在前库参数在后 gcc mysql_check.c -o mysql_check $(mysql_config --cflags) $(mysql_config --libs) # 运行前确认库路径必要时设置 ./mysql_check # 如果运行报找不到 .so用 ldd 确认实际加载路径 ldd ./mysql_check | grep mysql编译命令里$(mysql_config --cflags)和$(mysql_config --libs)分别展开成头文件参数和链接参数源文件mysql_check.c必须放在--libs展开的-l之前这是 5.4 那条坑的直接应用。运行后输出mysql client version: 8.0.xx说明连接和查询都通了。如果ldd显示not found回到 5.3 处理动态库路径。三步检查我一般按这个顺序走第一步file ./mysql_check确认可执行文件位数和预期一致第二步ldd ./mysql_check | grep mysql确认链到的是目标架构的库且路径存在第三步才是运行程序看输出。前两步过了第三步基本不会出问题反过来直接运行报错再去查往往要多绕几圈。32 位验证同理编译时加-m32file输出应为ELF 32-bitldd里库路径应指向 32 位目录。从那以后我每次在新机器上配 MySQL 开发环境都强制先跑一遍mysql_config --cflags --libs和这个最小连接程序确认头文件、库文件、运行时加载三关全过再动业务代码。这套习惯帮我省掉了大量「代码明明没问题却编不过」的排查时间。希望帮到你。本文还有配套的精品资源点击获取