1. 别去搜索引擎乱找,官网才是驱动唯一的“官方正确来源”
先聊点实际的。很多朋友一装 MySQL 驱动,第一反应就是去搜索引擎搜“mysql 驱动 jar 包下载”,然后点进那些下载站。这些站点的按钮套路多得要命,要么是假按钮、要么是捆绑下载器,十个里有八个会把你的电脑搞得乱七八糟。我见过不止一个同事在公司电脑上装了带捆绑的驱动下载器,结果整台机器连 IDE 都打不开了。咱们做开发、做运维,在这个上面折腾纯粹是浪费时间。
MySQL 官方提供的驱动其实就两大类:
- 面向 Java 应用的 JDBC 驱动,也就是通常说的 jar 包驱动,官方叫 Connector/J。
- 面向 Windows 等平台的 ODBC 驱动,官方叫 Connector/ODBC,适合在 Excel、Access、C++、Power BI 等工具里直接连接 MySQL。
之所以必须推荐从官网下载,一是能保证你拿到的是最完整的正式版本,二是不容易碰到恶意修改过的包,三是版本对得上号。网上很多个人转存的 jar 包,版本名看起来一样,但里面文件不全,甚至有些是拿旧版本改名的。数据库驱动的安全问题不是儿戏,一旦驱动被植入恶意代码,你的数据连接就等于裸奔。
所以这篇教程的目的很直接:把你带到 MySQL 官网下载页面,让你清楚地知道每一步该点什么、该选什么配置、下载完后怎么用。无论你是写 Java Web 项目的、还是用 Excel 做数据报表的,都能对照着完成。
在正式开始之前,我需要先点清楚一个核心概念:MySQL 驱动按用途划分,对应不同的开发场景。jar 包驱动面向 Java 生态,ODBC 驱动面向 Windows 生态。两者不冲突,但绝对不能混用。下面我会把两条线分别讲透。
2. 下载前必须搞清楚的 3 个问题
2.1 现在的 MySQL 驱动分几类,各自适合什么场景
先把“驱动”这个词掰开。MySQL 驱动不是一个文件打天下,官方维护的驱动至少有以下几类:
| 驱动名称 | 面向平台/语言 | 使用场景 |
|---|---|---|
| Connector/J (JDBC) | Java 全平台 | Java Web 项目、Spring Boot、Kotlin 等 JVM 语言 |
| Connector/ODBC | Windows / Linux / macOS | Excel 连接、Access、C++、Python (pyodbc) 、Power BI 等 |
| Connector/Python | Python | Python 程序连接 MySQL(官方推荐,但不少人仍用 PyMySQL) |
| Connector/NET | C# / .NET | C# WinForm、ASP.NET 项目 |
| Connector/C / C++ | C/C++ | 需要自己封装数据库访问的程序 |
从你标题里的热搜词看,“jar包驱动”和“ODBC”正是大家集中纠结的两个点。所以我把重点放在这两类上,其余的会顺带点一下,保证你以后遇到相关需求时知道还有别的选择。
2.2 Jar 包驱动和 ODBC 驱动到底有什么区别
这个区别用一句话说清:jar 包驱动是 Java 程序连接 MySQL 用的中间桥梁,它遵循 JDBC 规范,以 .jar 文件形式存在;ODBC 驱动则是 Windows(也包括其他系统)通用的数据库接口,任何支持 ODBC 的软件都能通过它访问 MySQL。
打个比方。JDBC 驱动像一条专为 Java 程序修的公路,Java 程序只需要知道 JDBC 接口怎么调用,驱动负责在后台完成和 MySQL 的通信。ODBC 驱动则像一条公共公路,不管你是 Excel、还是 C++ 写的程序,只要你的工具支持 ODBC 标准,就能用这条公路连接到 MySQL。
所以这个问题的回答其实很简单:
- 如果你在写 Java 代码,老老实实用 jar 包驱动。
- 如果你是想让 Excel 直接读取 MySQL 数据,或者你的程序是用 C++ 写的,那么 ODBC 驱动才是你要的。
千万别试图在 Java 项目里导入一个 ODBC 驱动,也不要在 Excel 里找 jar 包。这个方向错了,后面全是白忙活。
2.3 版本选择和 MySQL 服务端版本的对应关系
版本对齐是很多人忽略的坑。MySQL 驱动的版本号和 MySQL 服务器版本号并不是必须完全一致,但你需要关注驱动版本对服务器版本的最低要求和支持范围。
举个例子:MySQL 8.0 的服务器,用 MySQL Connector/J 5.1.49 也是能连的,但官方推荐使用 8.x 版本的驱动,因为旧驱动在新认证插件(caching_sha2_password)上会有兼容问题。相反,MySQL 5.7 的服务器,你拿最新的 Connector/J 8.4 去连,通常也没问题,驱动会做版本适配。
| MySQL 服务器版本 | 推荐驱动版本 | 说明 |
|---|---|---|
| 5.6 / 5.7 | Connector/J 5.1.x 或 8.0.x | 8.0.x 也兼容,但 5.1.x 更稳妥 |
| 8.0 / 8.4 / 9.x | Connector/J 8.x | 必须使用 8.x,因为默认认证插件不同 |
| 5.6 / 5.7 | Connector/ODBC 5.3.x | 老版本 ODBC 对接古老认证更省心 |
| 8.0 / 8.4 | Connector/ODBC 8.x | 对应 caching_sha2_password 认证 |
ODBC 驱动其实更加严格。MySQL 8.0 服务端默认使用 caching_sha2_password 加密认证方式,老版本的 ODBC 驱动(5.3 及之前)不一定支持这种新认证。如果连接时报“Authentication plugin 'caching_sha2_password' cannot be loaded”,那基本就是驱动版本太老。
博主实操心得:版本选择不要贪新,也不要贪旧
我自己的经验是:如果是在生产环境,驱动版本选择要跟着服务器版本来,选择官方标记为 GA(General Availability)的版本,不要把 Alpha、Beta 版本用在生产的工程项目里。很多人喜欢下载最新版,但最新版很可能有一些你没预料到的兼容性问题。宁可选择一个已经发布半年以上、大量人验证过的稳定版本。
还有一点,下载时记得看驱动的发布日期和对应服务器版本。官方网站的下载页面上,每个驱动版本都会列出支持的 MySQL Server 版本范围,这个信息是权威的,下载前花十秒钟看一眼,能省掉后面一小时的排查时间。
3. Jar 包驱动(Connector/J)下载完整流程
3.1 官网下载页面的正确进入方式与界面解读
进入官网的方法我再说一遍,不要通过搜索引擎,直接在浏览器地址栏输入 MySQL 官方下载地址:https://dev.mysql.com/downloads/。这一点值得重复三次,因为很多人搜出来的“官网”其实是个套壳下载站。认准 dev.mysql.com 这个域名,才是真正的开发者社区站点。
进入页面后,你会看到页面中间有个大大的 MySQL Community (GPL) Downloads 区域,里面列出了 MySQL 相关的各种下载项,包括 MySQL Community Server、MySQL Workbench、MySQL Shell 等。不要迷茫,你需要的驱动就在这个页面里。
找到页面上的“Connectors”栏目,点进去。这里会列出所有连接器的下载链接:Connector/J、Connector/ODBC、Connector/Python、Connector/NET 等。点击 Connector/J 这一行,就能进入到 jar 包驱动的下载专区。
3.2 选择平台、版本与文件类型的完整步骤
进入 Connector/J 下载页面后,你会看到一个下拉框,默认选项可能是“Select Operating System”。这里很多人会卡住——它是让你选操作系统平台的。如果你开发的是 Java 项目,而且用的不是跨平台部署的 Docker 镜像,这里其实选哪个都不影响 jar 包本身,因为 jar 包是纯 Java 字节码,不绑定操作系统。
但为了下载页面能列出文件列表,你总得选一个。一般选“Platform Independent”这个选项。选完之后,页面下方会出现一个文件列表,里面有两个压缩包:
.tar.gz后缀的压缩包:适合 Linux 和 macOS 环境。.zip后缀的压缩包:适合 Windows 环境。
名字里带有nojava标记的压缩包,说明里面不包含 Java 代码示例和文档,体积更小,只保留驱动核心 jar 文件。如果你只是想快速拿到 jar 包引入项目,可以直接下载nojava版本,省去解压后还要从一堆示例代码里翻 jar 的麻烦。
还有一个文件是.tgz,本质和.tar.gz一样,只是扩展名压缩方式略有区别,都是 Unix 类的归档文件,不用太纠结。
3.3 下载完成后 jar 包文件在哪里,怎么导入项目
下载完成后,解压压缩包,你会看到一个名为mysql-connector-j-8.x.x.jar的文件(旧版本可能叫mysql-connector-java-5.1.x.jar)。这个就是你需要的驱动核心文件。
把 jar 包引入项目,根据不同构建方式,有三种常用手段:
- 如果使用 Maven,直接在
pom.xml里添加依赖坐标,推荐用 Maven 中央仓库的依赖,比手动下载更优雅,也方便版本管理:
<dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <version>8.4.0</version> </dependency>- 如果使用 Gradle,在
build.gradle中加入:
implementation 'com.mysql:mysql-connector-j:8.4.0'- 如果是传统的 IDEV 工程(比如 Eclipse 或 IntelliJ IDEA 里创建的普通 Java 项目),直接把下载到的 jar 包复制到项目中的
lib目录,然后右键 jar 包,选择 “Add as Library”(IDEA 的操作方式)或 Build Path -> Add to Build Path(Eclipse 的操作方式)。
这里我要提一个很多人踩过的坑:不要只把 jar 包拖到项目目录下就完事,一定要在构建路径中引入该 jar 包。否则 IDEA 里可能自动识别了,但一到命令行打包运行时就会报ClassNotFoundException: com.mysql.cj.jdbc.Driver。
3.4 验证驱动是否生效的标准代码片段
驱动导入项目后,用一段最简单的代码验证一下,看数据库是否能正常连接。下面这段代码我用了很多年,几乎没有失败过:
import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; public class MySQLConnTest { public static void main(String[] args) { String url = "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai"; String user = "root"; String password = "your_password"; try { Class.forName("com.mysql.cj.jdbc.Driver"); Connection conn = DriverManager.getConnection(url, user, password); System.out.println("数据库连接成功:" + conn.getCatalog()); conn.close(); } catch (ClassNotFoundException e) { System.out.println("找不到驱动类,请检查 jar 包是否导入正确"); e.printStackTrace(); } catch (SQLException e) { System.out.println("数据库连接失败,请检查 URL、账号密码或网络"); e.printStackTrace(); } } }注意 URL 里面serverTimezone=Asia/Shanghai这个参数。MySQL 8.0 及以上版本的驱动要求显式指定时区,否则会报The server time zone value 'Öйú±ê׼ʱ¼ä' is unrecognized之类的错误。这个错误曾经坑掉了不知道多少新手,甚至有些老手换版本后也会踩到。
博主实操心得:驱动类名不是随随便便写的
新旧版本驱动的类名不一样,这也是常见报错来源之一:
- MySQL Connector/J 5.x 的驱动类名是
com.mysql.jdbc.Driver - MySQL Connector/J 8.x 的驱动类名是
com.mysql.cj.jdbc.Driver
写Class.forName的时候,用错类名会直接报ClassNotFoundException。如果你用的是 8.x 驱动却写 5.x 的类名,它找不到类。如果你在 8.x 下写 5.x 的类名,有时候反而会成功,因为 8.x 为了向后兼容还保留了旧类名,但会打印一条警告信息,提示你已经过时了。我的建议是:新项目一律用新类名,不要给自己留这种兼容性的隐患。
4. ODBC 驱动下载完整流程
4.1 谁需要 ODBC 驱动,常见使用场景盘点
ODBC 驱动在开发圈子里没有 jar 包驱动那么“程序员味”,但它是个威力巨大的工具。你不需要写代码、不需要引入类库,只要在系统里装好 ODBC 驱动,配置好数据源,然后任何支持 ODBC 的软件都能直接读取 MySQL 数据。
我见过的典型使用场景有:
- 数据分析人员用 Excel 直接连接 MySQL,做数据透视表和报表,不需要把数据导出成 CSV 再导入。
- 用 Access 连接 MySQL,把 Access 当前端的表单和报表工具,MySQL 当后端数据库。
- 用 Python 的 pyodbc 库连接 MySQL 做数据处理。
- 用 C++ 写的 Windows 桌面程序,不想自己封装 TCP 协议,直接通过 ODBC API 访问数据库。
- Power BI / Tableau 等 BI 工具作为数据源连接 MySQL。
这些场景下,ODBC 驱动是你唯一的桥梁。它把 MySQL 的通信协议封装成符合 ODBC 标准的接口,让上面所有工具都能用一套标准化的方式去访问。
4.2 官网 ODBC 驱动下载步骤:操作系统选择与安装包位数的关键细节
ODBC 驱动的下载页面同样是https://dev.mysql.com/downloads/connector/odbc/。进入后你会看到操作系统的下拉框,这次选择操作系统是真的有影响,因为 ODBC 驱动是编译好的二进制程序,不是 Java 那种跨平台字节码。
选择你的操作系统后,比如 Windows,页面会列出两个安装包:
- 一个 32 位版本的 .msi 安装包
- 一个 64 位版本的 .msi 安装包
这里千万要注意位数的问题。ODBC 数据源管理器也有 32 位和 64 位之分,很多软件是 32 位版本的,比如旧版的 Office Excel(Office 2010 之前)、或者某些 32 位开发的 C++ 程序,它们只能调用 32 位 ODBC 驱动。如果你只安装了 64 位驱动,这些 32 位程序在配置数据源时会发现找不到驱动。
我的建议是:如果你的操作系统是 64 位的 Windows,且使用场景不明确,那就两个版本的驱动都装上,反正它们可以共存,不会冲突。这样既能满足 64 位软件的需求,也能兼容 32 位的老软件。
4.3 Windows 下 ODBC 驱动的安装过程与数据源配置全程
安装过程本身是标准的 Windows 软件安装流程,双击.msi文件,一路点 Next,接受许可协议,选择安装路径,安装完成后不需要重启电脑。
安装完成后重头戏来了:配置 ODBC 数据源。很多新手装好驱动后发现还是连不上数据库,原因就是没有在系统里配置数据源。
Windows 10/11 下打开 ODBC 数据源管理器的方法:
- 按
Win + R键,输入odbcad32.exe并回车(64 位系统默认打开的是 64 位版本)。 - 如果你需要配置 32 位数据源,那要运行
C:\Windows\SysWOW64\odbcad32.exe。这个路径是不是很反直觉?64 位系统里 SysWOW64 目录下放的反而是 32 位工具,为的是兼容老程序。注意别搞混。
打开数据源管理器后,选择“系统 DSN”或“用户 DSN”标签页——推荐选择“系统 DSN”,因为这个数据源对整个系统的所有用户都可用,而不会出现你在自己账号下配置好了、换一个账号又找不到的情况。
点击“添加”,弹窗里选择“MySQL ODBC 8.3 Unicode Driver”,然后点击“完成”,就会出现 MySQL 连接配置窗口。在这里填写:
- Data Source Name:数据源名称,自己取一个友好的名字,比如
LocalMySQL。 - Description:随便填,或者不填。
- TCP/IP Server:填
127.0.0.1或实际 MySQL 服务器的 IP。 - Port:MySQL 端口,默认 3306,除非你改过。
- User:MySQL 用户名,比如
root。 - Password:对应的密码。
- Database:想要默认连接的数据库,可以暂时留空,连接后再选。
填完后点击“Test”按钮,如果显示 “Connection successful”,说明配置成功,点击确定保存。
4.4 利用 ODBC 驱动在 Excel 里直接读取 MySQL 数据的实操演示
数据源配置好后,怎么在 Excel 里验证呢?我演示一个最常见的场景,Excel 直接连接 MySQL 并拉取数据。
打开 Excel(推荐使用 2016 或更新版本,操作路径略有差异但原理一样),点击“数据”选项卡,在“获取外部数据”区域选择“自其他来源”,然后选择“来自 ODBC”或者“自数据连接向导”。
在弹出的窗口里选择你刚才配置好的数据源名称LocalMySQL,点击“连接”。
如果数据源配置正确,Excel 会提示你选择要导入的表或视图。选中你要的数据表,点击“确定”,然后选择数据要存放的位置,Excel 就会把 MySQL 里的数据拉取到工作表中,并且建立连接。后续你在 Excel 里刷新,数据就会从 MySQL 重新拉取一遍。
这里有一个实际工作中的细节:如果你的 MySQL 表中数据量非常大(几十万行以上),直接用 Excel 拉全表数据是不现实的,Excel 的行数上限是 104 万行左右,超过之后数据会被截断。更合理的做法是在“导入数据”窗口里写 SQL 查询语句,只提取你需要的字段和行数。例如:
SELECT id, name, amount, create_time FROM orders WHERE amount > 1000 ORDER BY create_time DESC LIMIT 10000;这个查询只拉取 1 万行金额大于 1000 的订单数据,既满足分析需求,又不会把 Excel 拖死。
博主实操心得:测试连接成功但业务程序连接失败的多半是 DSN 位数问题
我遇到过不少情况:ODBC 驱动装好了,在 64 位数据源管理器里测试连接也成功了,但是某个老软件就是连不上数据库,甚至软件内部配置数据库时根本看不到你创建的 DSN。
那时候排查了很久,最后发现原因:那个老软件是 32 位程序,它去找数据源时找的是 32 位 ODBC 数据源管理器里的配置。而我们在 64 位管理器里配置的 DSN,在 32 位程序眼里根本不存在。
解决办法很简单:运行 32 位数据源管理器,把同样的数据源再配置一遍。两边都配上,老程序就能正常工作了。这个经验帮我在朋友的数据库迁移项目里省下了不少时间。
5. 驱动连接失败的常见问题与排查手册
5.1 Jar 包驱动连接失败的 5 个经典报错与逐条解法
这部分我整理了实际工作中见到最多的 jar 包驱动连接问题,每条都是真金白银换来的排查经验。
| 报错信息 | 原因 | 解决方法 |
|---|---|---|
ClassNotFoundException: com.mysql.cj.jdbc.Driver | jar 包未正确导入项目构建路径 | 重新检查项目依赖配置,Maven 项目确认仓库是否成功下载 |
Access denied for user 'root'@'localhost' | 用户名密码错误,或者该用户名不允许从当前主机连接 | 检查密码大小写,确认 MySQL 用户的 host 权限 |
The server time zone value ... is unrecognized | 驱动版本较新,要求显式指定时区 | URL 后面加serverTimezone=Asia/Shanghai |
Public Key Retrieval is not allowed | 使用 caching_sha2_password 认证且连接未加密,驱动默认不允许获取公钥 | URL 加参数allowPublicKeyRetrieval=true,开发环境可以用,生产环境建议改用 SSL |
Communications link failure | 网络不通,或者 MySQL 连接数满了,或者 mysql 的 bind-address 配置限制了 | 先用 ping 和 telnet 测试 3306 端口,再看 MySQL 的 max_connections |
第二行的问题里有一种特殊情况:MySQL 8.0 默认创建的用户认证插件是caching_sha2_password,如果驱动版本太旧(小于 5.1.47),连认证都无法完成。这时候要么升级驱动,要么在建用户时指定mysql_native_password,但我不建议降级认证方式,因为 caching_sha2_password 要比老的方式安全得多。
第四行的问题在开发环境比较高发。你用 root 连本地数据库时,连接串没有加 SSL 参数,MySQL 8.x 默认用 caching_sha2_password 认证,驱动需要先从服务器获取公钥。你需要在连接串上追加allowPublicKeyRetrieval=true&useSSL=false。这个参数在生产环境不要随便用,因为关闭了 SSL 和公钥获取限制,数据会明文传输,有被截获的风险。
5.2 ODBC 连接失败的常见原因与解决建议
ODBC 驱动连接失败,和 jar 包驱动不完全一样。因为 ODBC 是通过数据源(DSN)连接数据库,中间多了操作系统这层抽象的配置,排查顺序就不一样。
我总结了一个排查顺序,是从实际工作中提炼出来的:
第一,先确认 MySQL 服务能不能接受本地连接。在 MySQL 命令行工具里执行SELECT 1;能返回正常结果,说明服务端没问题。这一步如果失败,后面什么都白搭。
第二,测试 TCP/IP 端口通不通。在命令行执行:
telnet 127.0.0.1 3306如果你看到黑窗口变空白,说明端口通着;如果立即提示“无法打开到主机的连接”,说明 MySQL 没有监听该端口,或者防火墙拦截了。Windows 上有时候还需要在防火墙里单独放行,你可以临时把防火墙关掉测试一下,通的话再加回防火墙放行规则。
第三,用 ODBC 数据源管理器自带的 Test 按钮测试连接。这个测试是最直观的,它能直接告诉你用户名密码对不对、数据库存在不存在。
第四,如果 Test 按钮成功,但你的程序还是连接失败,那么一定是位数问题。回去检查你的程序是 32 位还是 64 位,然后去对应位数的 ODBC 管理器里重新配置数据源。
第五,检查 MySQL 用户连接权限。MySQL 默认的 root 用户在很多安装配置下只允许从本机连接。如果用 ODBC 数据源填的是 MySQL 服务器的 IP,但连接的是远程数据库,你需要确保 MySQL 里有一个授权用户允许从你的机器连接。如果报Host 'xxx' is not allowed to connect to this MySQL server,那就需要在 MySQL 里授权或新建用户:
CREATE USER 'analyst'@'%' IDENTIFIED BY 'your_password'; GRANT SELECT ON mydb.* TO 'analyst'@'%'; FLUSH PRIVILEGES;这个 SQL 创建了一个任意主机都能连接的 analyst 用户,并且只授予了 mydb 库的 SELECT 权限,原则是最小权限原则。
5.3 字符集乱码问题:驱动连接时的 charset 参数配置
乱码问题在驱动连接中极其常见。数据库用 UTF-8 存中文,结果程序读出来是问号,或者写进去变乱码。驱动的连接字符集参数如果不设置,MySQL 默认会使用服务端的character_set_server配置,而这个值在很多默认安装下是latin1,不是utf8mb4。
对于 jar 包驱动,解决办法是在 JDBC URL 中加上characterEncoding=utf8:
String url = "jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8";对于 ODBC 驱动,在配置数据源时,“Connection”选项卡里可以设置 Connection Character Set,选择utf8或utf8mb4。这里建议选择utf8mb4,因为 MySQL 的 utf8 其实最多存 3 个字节,有些特殊字符(emoji 和生僻汉字)需要 4 个字节,用 utf8 字符集存储会报错或乱码。utf8mb4 是 utf8 的超集,完全兼容并且支持 4 字节字符,是现代 MySQL 应用的标准选择。
5.4 驱动版本不兼容引发的隐藏问题:从报错到定位
版本不兼容不总是直接报错的,有时候是“能用但时不时报错”。我遇到过一种情况:用 Connector/J 5.1.48 连接 MySQL 8.0 的数据库,平时查数据没问题,但在执行某些特定 SQL(比如新的窗口函数、CTE 语法)时会报语法错误。原因很简单:服务器的 SQL 解析器支持这些新语法,但驱动把 SQL 发送出去时走的还是旧协议,在某个环节认不出新语法。
这类问题的定位技巧是:看报错发生在哪个阶段。如果报错信息是 SQL 语法错误,先拿同一句 SQL 直接在 MySQL 命令行执行一遍,如果命令行能执行而程序报错,那基本就是驱动版本太旧、不认识新语法。这种情况升级驱动版本就好。
还有一类隐藏问题:驱动版本过新但服务器版本太老。比如用最新的 Connector/J 9.x 去连 MySQL 5.6,驱动可能在握手阶段就要求服务端支持某种新的校验方式,老服务器不支持,于是报错。解决方式还是那句话:让驱动的重大版本和服务器保持同一代次。服务器 5.7 配驱动 8.x 这种“跨一代”通常没问题,但跨两代就有点悬了。
博主实操心得:排查问题时一定要学会看驱动日志
驱动连接报错时,简单的报错信息往往不够用。Java 项目中可以在启动参数中增加:
-Dorg.slf4j.simpleLogger.log.com.mysql.cj=debug如果是 Maven 项目,可能会需要先引入 slf4j-simple 依赖。ODBC 驱动在 Windows 下也可以打开 “Enable ODBC trace log” 选项,它会把 ODBC 调用过程完整记录到文本文件里。这些日志能帮你看到问题到底出在握手阶段、认证阶段还是 SQL 执行阶段,能少走非常多弯路。
6. 驱动下载之后:几个容易忽略的操作细节
6.1 Jar 包放进 lib 目录后还需要执行的操作
很多人在传统工程里把 jar 包下载下来、拖进 lib 目录,然后启动项目就报错。这不一定是你操作有问题,可能是 IDEA 没把 lib 目录识别成依赖目录。
IDEA 里正确的做法:在项目根目录新建 lib 文件夹,把 jar 包复制进去,然后右键 jar 包,在右键菜单选择 “Add as Library”。之后在弹出的对话框里确认 “Project Structure” 的 Modules 里多出了这个依赖。
Eclipse 的做法类似,右键 jar 包选择 “Build Path” -> “Add to Build Path”。
如果你使用的是 Maven 或 Gradle,我更推荐直接通过 Maven 中央仓库拉取驱动依赖,而不要手动下载 jar 包。原因有三点:
- 版本管理方便,Maven 会自动传递依赖。
- 你不需要每次换电脑都手动拷贝 jar 包。
- Maven 中央仓库的驱动包经过安全验证,不存在被篡改的风险。
6.2 ODBC 驱动的版本选择:Unicode 驱动和普通驱动的区别
在 ODBC 驱动安装过程中,你会看到安装选项里有 “Unicode Driver” 和 “ANSI Driver” 两个组件。很多人在这一步直接跳过,结果在配置数据源时发现列表里只有 “MySQL ODBC 8.0 Unicode Driver”,少了一个非 Unicode 的选项。
Unicode 驱动的意思是驱动内部用 UTF-16 编码处理字符串,支持任何语言的字符。而 ANSI 驱动使用系统默认编码,在 Windows 上通常是 GBK,在处理多语言字符时会出问题。现在的软件和数据基本都是 Unicode 的,所以安装时直接把两个驱动都装上,配置 DSN 时也优先选用 Unicode Driver。
补充一句:如果你用的是 Python 的 pyodbc,官方文档里也是推荐用 Unicode 驱动,否则中文数据可能乱码。这个细节我用一次踩一次坑,后来总结出了一个原则:有 Unicode 就用 Unicode。
6.3 驱动的后续维护与更新建议
很多人装好驱动后就没有然后了,直到某天 MySQL 升级,程序就宕了。
驱动的更新节奏不必太频繁,但也不应该完全不管。我的建议是:
- 每半年或者一年,去官网查看一下当前使用的驱动是否有重要安全更新。
- 如果 MySQL 服务器要做大版本升级(比如 5.7 升到 8.0),驱动一定要提前做好适配测试,最好在测试环境里先模拟一遍。
- 关注官方驱动的“生命周期”信息。MySQL 官方会为每个驱动版本设定支持截止日期,超出日期的版本不再接收安全补丁。继续使用过期的驱动,就像用着不再更新的老旧系统,安全风险只能自己扛。
我见过一个项目用了 5 年 Connector/J 5.1.38,没有任何问题,于是大家都不去动它。但后来因为安全审计发现这个版本的 JDBC 驱动存在已知漏洞,才被迫升级。升级过程中也碰到了一些兼容性问题,多花了不少时间。早知如此,不如当初每半年检查一次,主动升级,成本要低得多。
博主实操心得:把驱动版本记录在项目文档里
我强烈建议所有项目都在 README 或者数据库配置文档里记录一个“环境版本清单”,里面写明 MySQL Server 版本、Connector/J 或 Connector/ODBC 的版本、安装日期。这个习惯看起来不起眼,但等到半年后你接到一个“为什么突然连不上数据库”的工单时,它能帮你迅速判断是不是驱动版本和服务器版本不匹配。我在实际工作中,这种版本清单已经帮我排查了多次不明原因的问题。
7. 写在最后的一点经验之谈
驱动下载这件事,看起来是“下载一个文件而已”,实际里面藏了不少细节。版本选型、位数匹配、路径配置、字符集设置,每一步都有可能出问题。这篇教程整理的是我多年项目中的路径和方法,每一步都是验证过的,希望能帮助你在 MySQL 驱动的下载和配置上节省时间。如果你按照这个流程走下来还是遇到了问题,建议先从驱动版本下手排查,那是最常见也最容易被忽略的原因。