简介：这是一份面向 Java 初学者与刚接触 Eclipse 的开发者的 MySQL 连接实操资料，核心目标是把环境配置、驱动导入、代码编写到查询/插入数据这条链路讲清楚。资料从 MySQL 建库建表开始，给出 JDBC 驱动导入 Eclipse 的具体操作方法，并附带连接测试与批量插入示例代码，同时提醒在真实项目中改用 PreparedStatement 以防注入、及时关闭连接等注意事项，具备一定排错参考价值。压缩包为 1 个 pdf 文件，大小 75KB，内容为图文对照的步骤说明，适合边看边操作。该资源已有 10436 人学习下载，使用人数较多，说明对入门阶段解决环境连接问题有较普遍的参考意义。按文中的建库、导驱动、写代码三个层次实践，可以较快跑通 Eclipse 连接 MySQL 并完成基本数据读写。
1. 用Eclipse连接MySQL数据库：先看清这条链路断在哪
“用Eclipse连接MySQL数据库”听起来是个连入门都算不上的基础操作，可真上手之后，一整晚折腾不出来的情况太常见了。常见的翻车姿势包括：MySQL装好了却不记得建库建账号、驱动jar放进项目但没挂到classpath、驱动类名写错、跑起来报SSL和时区错误，每一处都能把人卡死。这篇文章要做的是把整条链路拆开：从MySQL账号准备、JDBC驱动选择，到Eclipse项目里配置Build Path和写第一段能跑通的连接代码，最后给出按报错现象排查的清单。适合刚装完Eclipse和MySQL、准备做JavaWeb或普通Java项目的人，也适合在旧项目里换数据库连接、想确认参数没配错的人。读完这套步骤，至少能获得一份可以直接照着复现的配置方法。
2. 连接前的三件事：账号权限、驱动jar、Eclipse项目结构
在Eclipse里写代码之前，先把MySQL侧和驱动侧准备到位。很多人跳过准备工作直接开写，最后连不上又回头查环境，反而更慢。这三件事做完，后面的连接代码就是水到渠成的事。
2.1 在MySQL侧先建好库、账号和权限：三条SQL搞定
最常见的做法是给这个项目单独建一个账号，而不是直接拿root去连。拿root连本地库在练习阶段确实能通，但团队项目里配置文件会在多台机器、多个环境之间流转，root权限一旦带上去，后面写脚本、部署、交接都容易出问题。所以先登录root，给项目建一个独立的库和账号。
mysql -uroot -p登录成功后执行下面这组SQL。这里的库名、账号、密码都是演示用的，实际项目中按你自己的规范替换，但结构保持这个套路。
CREATE DATABASE demo CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER 'demo'@'localhost' IDENTIFIED BY 'DemoPass123'; GRANT ALL PRIVILEGES ON demo.* TO 'demo'@'localhost'; FLUSH PRIVILEGES;第一条语句建库，字符集指定utf8mb4，这样存中文、表情符号都不会乱码，collate用utf8mb4_general_ci在排序和比较时够用且兼容性好。第二条建账号，'demo'@'localhost'里的localhost表示只允许从本机连接，如果你的Eclipse和MySQL不在同一台机器，这个位置要改成'demo'@'%'或指定IP。第三条授权，把demo库的所有权限给这个账号，但只限于demo库，不影响其他库。第四条让权限立即生效。
执行完以后，建议先用命令行验证一次，确认这个新账号能正常登录：
mysql -udemo -pDemoPass123 demo这一步能提前过滤掉账号密码写错、IP限制导致连不上的问题。命令行能进去，说明MySQL侧已经通了，后面再排查就是Eclipse和驱动侧的事。
2.2 JDBC驱动版本怎么挑：先看MySQL大版本，再看Java版本
驱动是Java程序和MySQL之间唯一的桥梁，选错版本是另一个常见坑。驱动类名的分水岭在MySQL 8：老驱动用com.mysql.jdbc.Driver，MySQL 8.x起官方推荐用com.mysql.cj.jdbc.Driver。老类名在新驱动里虽然勉强能用，但会打警告，新项目不要再用。
选型逻辑其实不复杂，两条规则足够。第一条，驱动大版本和MySQL大版本对齐：MySQL 5.x配Connector/J 5.x，MySQL 8.x及以上配Connector/J 8.x。第二条，驱动要满足项目JDK版本：新驱动基本要求JDK 8或更高，老驱动虽然能在旧JDK上跑，但在新版JDK上可能遇到SSL和反射相关的问题，得不偿失。按这个策略，新项目一律用新驱动，旧项目除非有历史包袱，否则别守着老版本不动。
| MySQL版本 | 驱动选择 | 驱动类名 |
|---|---|---|
| MySQL 5.x | Connector/J 5.x | com.mysql.jdbc.Driver |
| MySQL 8.x及以上 | Connector/J 8.x | com.mysql.cj.jdbc.Driver |
下载时认准官方Maven仓库里的mysql-connector-j，版本号按上面规则选。驱动jar压缩包里有一个META-INF/MANIFEST.MF文件，打开能看到该驱动要求的最低Java版本，JDK版本拿不准时翻一下这个文件最靠谱。
2.3 把驱动jar放进Eclipse项目的lib目录：先建目录再引jar
驱动下载好以后，不是随便往Eclipse里一拖就能用。我一般在新建项目时就顺手建一个lib目录，专门放jar包，然后把这个目录里所有jar统一挂到Build Path。这样项目结构清楚，换机器、换工作区也不会出现引用路径断裂的问题。
操作步骤：右键项目名，New，Folder，命名lib。把下载好的驱动jar复制到这个目录。此时jar还只是普通文件，Eclipse不会自动把它加入编译路径，下一步要在Java Build Path里手动挂载，这就是下一章的内容。这里提前说一下，后续添加jar时用Add JARs，不要用Add External JARs。前者会把jar以项目相对路径方式记录，项目整体拷贝到别的机器还能用；后者记录的是绝对路径，一换电脑就报找不到驱动类，这是很多人换工作区后连接程序突然失效的原因。
3. 在Eclipse里挂上驱动并跑通第一段连接代码
环境准备到位之后，这章把项目配置和连接代码串起来。目标只有一个：让一段最小代码在Eclipse里跑通，控制台看到连接成功的信息。
3.1 用Project Properties把驱动挂到Build Path：三步操作
右键项目，选择Properties，在左侧找到Java Build Path，切到Libraries页签。点击Add JARs，在弹出的文件树里展开项目根目录下的lib，选中刚才那个驱动jar，确定，最后Apply and Close。
挂到Build Path的含义是把jar加入编译和运行时的classpath，Eclipse会把这个jar下的所有class变成项目可见。这一步做完，在Java代码里import DriverManager等类才有意义。检查是否挂成功有个笨方法：在项目里新建一个类，输入com.mysql.cj.jdbc.Driver看能否自动补全出这个类名，能补全说明classpath已经识别到驱动了。
3.2 最小连接代码：TestConnection类与每个参数的用意
新建一个类，命名为TestConnection，main方法里写最精简的连接逻辑。下面是完整可跑的代码：
import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; public class TestConnection { public static void main(String[] args) { String url = "jdbc:mysql://localhost:3306/demo" + "?useSSL=false" + "&serverTimezone=Asia/Shanghai" + "&characterEncoding=utf8" + "&allowPublicKeyRetrieval=true"; String user = "demo"; String password = "DemoPass123"; try (Connection conn = DriverManager.getConnection(url, user, password)) { System.out.println("连接成功：" + conn); } catch (SQLException e) { e.printStackTrace(); } } }这段代码没有写Class.forName("com.mysql.cj.jdbc.Driver")，因为新驱动通过SPI机制在DriverManager里自动注册，老写法在新驱动下不是必须的。如果你的驱动版本比较旧，或者项目里有历史代码习惯了显式注册，加上也不影响运行。getConnection方法内部会完成TCP连接、认证、建立会话整个过程，返回的Connection对象代表一条实际可用的数据库连接。
代码里的url是核心。jdbc:mysql://是协议头，localhost:3306是MySQL所在主机和端口，demo是库名。从?开始是连接参数，每个参数用&隔开。try-with-resources写法保证连接用完后自动关闭，避免连接泄漏。运行后如果控制台输出“连接成功：...”并带出一串连接对象信息，说明链路已经通了。如果报错，先看下一章排查清单，大多数错误都能对应上。
3.3 连接串里的5个必调参数：useSSL、serverTimezone、characterEncoding、allowPublicKeyRetrieval、connectTimeout
上面url里那四个参数不是随手写的，去掉任何一个都可能报错或出现奇怪问题。还有一个connectTimeout参数建议也加上。这五个参数拼在最后的?后面，是JDBC URL标准写法，后面接数据库连接池时这套配置也能直接复用。
| 参数 | 建议值 | 作用与踩坑说明 |
|---|---|---|
| useSSL | false | 开发环境非加密连接，避免证书校验失败；生产环境必须设为true并配置CA证书 |
| serverTimezone | Asia/Shanghai | 驱动连接MySQL时会区不明确直接报错，这个参数显式指定时区 |
| characterEncoding | utf8 | 配合数据库端utf8mb4，保证中文不乱码 |
| allowPublicKeyRetrieval | true | MySQL 8默认认证插件下，非SSL连接获取服务端公钥的开关 |
| connectTimeout | 5000 | 单位毫秒，连不上时快速失败，默认超时可能卡几十秒 |
serverTimezone这个参数最容易踩坑。数据库所在地时区不是UTC也不是系统默认值时必须显式写，写成Asia/Shanghai比GMT%2B8更直观，因为+在URL里要编码成%2B，写错就报时区错误。allowPublicKeyRetrieval只在使用MySQL 8默认的caching_sha2_password插件时才有意义，旧版本MySQL不需要。connectTimeout是保命参数，连不上的时候让程序5秒内报错退出，否则默认情况下卡到TCP超时，很影响调试感受。
把上面这些参数补进url再跑一次，连接成功率会高很多。还没通的话，下一章把高频报错按现象列出来，照着自己比对就行。
4. 常见连接失败排查：现象、原因、给到能抄的解决
连接数据库出错，看报错信息比网上乱搜更高效。下面几条是连接MySQL时最高频的报错，每条按照“现象 → 原因 → 解决”来写，实际问题基本都能落到其中一条。
4.1 Connection refused / error 2002：是MySQL没起，还是端口不对
现象是Eclipse里报Connection refused或者Communications link failure。如果MySQL在Linux上部署，命令行也可能报ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock'。
原因分两类：一类是MySQL服务没启动，另一类是端口或监听地址不对。socket类型的报错通常说明mysqld进程没起来，TCP类型的报错可能是端口不是3306，或者MySQL只监听了loopback而Eclipse在另一台机器。
解决方法是先确认MySQL进程存在。Linux下用ss -lnt | grep 3306看端口有没有监听，Windows下看服务列表里MySQL服务是否在运行。然后用命令行登录一次，能登进去说明服务侧没问题，问题大概率在URL里的主机名或端口写错，回头核对Eclipse里url的localhost:3306这一段。
4.2 Public Key Retrieval is not allowed：MySQL 8认证插件引起的
现象是报Public Key Retrieval is not allowed这一整串异常，前面往往还有Unable to connect。这是MySQL 8.x开始用了默认的caching_sha2_password插件，在非SSL连接下，客户端需要向服务端请求公钥来加密密码，而驱动默认不允许这个动作。
原因是驱动设置和MySQL认证方式不匹配。解决方式最直接：在连接url后面加allowPublicKeyRetrieval=true，配合useSSL=false一起使用。这个参数只针对MySQL 8的认证插件，老版本MySQL不会遇到。如果加了参数还报错，确认一下驱动是不是8.x系列，老驱动对这个参数支持不好。
4.3 The server time zone value is unrecognized：时区不写死就会报
现象是在连接阶段抛异常，核心提示是The server time zone value 'xxx' is unrecognized or represents more than one time zone。原因是MySQL服务器时区设置不明确，驱动拿不到有效时区值进行转换。
解决方式是在url里显式指定serverTimezone=Asia/Shanghai。国内机器的数据库环境时区五花八门，EST、CST这些缩写在不同系统里含义还冲突，最省事的做法就是java代码里写死。如果项目要求跟随服务器时区，可以设serverTimezone=GMT%2B8，注意加号在URL里不能直接写。
4.4 ClassNotFoundException：驱动jar没挂到classpath
现象是运行时报ClassNotFoundException: com.mysql.cj.jdbc.Driver，但Build Path里看得到jar。这种情况在Eclipse新版本里尤其多，重启项目或Clean后丢classpath配置也是老问题。
原因基本是两种：jar没有真正挂到classpath，或者挂的是External JARs形式的绝对路径，项目换位置后就失效了。解决方式：先展开Java Build Path的Libraries页签，确认驱动jar真的在列表里；再确认挂载方式是用Add JARs而不是Add External JARs。如果确认配置没问题还是报错，执行一次Project菜单下的Clean清掉编译缓存再跑。
4.5 SSL连接错误：开发环境关闭，生产环境保持开启
现象是连接时抛SSLHandshakeException，或者报证书相关的异常，这出现在驱动默认useSSL=true的自签名证书场景下。顺便说清楚一个容易混淆的点：MySQL官方客户端和很多DBA工具里看到的参数叫sslmode，而JDBC驱动Connector/J里的对应参数是useSSL，两者作用类似但参数名不同，网上搜索时注意区分，别把sslmode写进JDBC url。
原因是驱动默认尝试加密连接，而本地开发环境一般没有配置CA证书，握手时就挂了。本地开发且网络环境可控的前提下，url里加useSSL=false即可关闭加密。生产环境的连接必须保持useSSL=true，并且配置正确的证书，不能为图省事关掉加密。另外有一个容易被忽略的问题：如果url里只写了useSSL=false但三个全英文环境变量没配全，下面一小节的字符集问题也会冒出来。
4.6 中文乱码和SQL注入的边界问题：characterEncoding别和数据库端字符集脱节
现象是连接正常、查询也正常，但插入的中文变成问号，或者查询条件里的中文匹配不上。原因是连接串的characterEncoding和数据库实际字符集不一致，多数是库建成了latin1而连接串设置utf8，或者反过来。
解决方式：建库时统一用utf8mb4，连接url里写characterEncoding=utf8，两端对齐后重启应用再测。这里顺便提醒一下，字符集的问题排查优先级不高，但如果发现乱码是偶发性出现的，优先检查数据库连接池的初始化SQL里有没有单独设置连接字符集，那一条优先级高于url参数。
5. 把连接参数收进配置文件：换库不停机，连上了先打印版本号
连接代码能跑通之后，下一步不是急着写业务，而是把连接参数从代码里拆出去。直接把密码写在Java文件里有两个坏处：一是代码入库后密码跟着泄漏，二是换个测试库还得改代码重新编译。常见做法是建一个db.properties放在src目录下，用一行行键值对管理连接串，后面接HikariCP、Druid这类数据库连接池时，这套参数可以直接搬进池子配置。
5.1 用db.properties管理连接信息
db.url=jdbc:mysql://localhost:3306/demo?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8&allowPublicKeyRetrieval=true&connectTimeout=5000 db.user=demo db.password=DemoPass123配套的读取工具类也很固定：
import java.io.InputStream; import java.sql.Connection; import java.sql.DriverManager; import java.util.Properties; public class DbUtil { private static final Properties PROPS = new Properties(); static { try (InputStream in = DbUtil.class.getClassLoader() .getResourceAsStream("db.properties")) { PROPS.load(in); } catch (Exception e) { e.printStackTrace(); } } public static Connection getConnection() throws Exception { return DriverManager.getConnection( PROPS.getProperty("db.url"), PROPS.getProperty("db.user"), PROPS.getProperty("db.password")); } }注意db.properties放在src根目录，这样编译后进入classpath，getResourceAsStream才能找到它。生产环境里密码建议通过环境变量或配置中心注入，不要在文件里保留明文，但开发阶段用properties是通用且高效的做法。
5.2 连接验证：打印MySQL版本号而不是只输出“连接成功”
验证连接是否真正可用，最直接的方式是执行一条SELECT VERSION()，把数据库返回的版本号打出来。这能确认两件事：连接真的建立成功了，并且连到了预期版本的MySQL实例。
import java.sql.Connection; import java.sql.ResultSet; import java.sql.Statement; public class VerifyConnection { public static void main(String[] args) throws Exception { try (Connection conn = DbUtil.getConnection(); Statement st = conn.createStatement()) { ResultSet rs = st.executeQuery("SELECT VERSION()"); if (rs.next()) { System.out.println("Connected to MySQL: " + rs.getString(1)); } } } }这个验证类在以后排查环境问题时也很有用：比如怀疑连错了库、驱动版本不对、MySQL参数被改过，先跑一遍它，看版本号和连接是否正常，能快速收敛排查范围。我现在的习惯是，只要是Java连数据库的工程，第一件事永远是先把db.properties和这个验证类写好，再写业务代码。这个习惯帮我少踩了很多后期才暴露的连接配置坑，希望帮到你。
本文还有配套的精品资源，点击获取
表面吸附的VASP计算全流程：从Materials Studio建模到吸附能分析)