做 Unity 项目的时候突然要接数据库第一反应多半是头大。当年我在某个截单工具类项目里遇到同样的需求——Unity 里展示后台记录、保存玩家操作日志、按条件筛选数据这些都是典型的数据持久化场景。而选择“Unity 2020 VS2017 连 MySQL”这套组合当时也是对比了好几轮才定的。先说结论这方案完全可行但坑也不少。最典型的坑就是 MySQL 数据驱动 DLL 的版本兼容问题其次是 Unity 的 API Compatibility Level 配置再就是连接字符串踩出一堆连接失败。这篇文章从头到尾把我实际跑通过的路走一遍从环境选型、DLL 引入、连接配置到完整脚本和常见问题排查全程按照我踩坑之后的正确顺序来讲保证是可复现的实操流程。如果你正在做 Unity 客户端、需要直连 MySQL 做工具类应用或内部管理端或者只是一个想搞明白“Unity 能不能连数据库”的新手这篇能帮你少走至少一个星期的弯路。1. 整体方案设计与选型逻辑1.1 为什么是 Unity 2020 VS2017Unity 2020 是 LTS 版本里的分水岭。它不再像 2018 那样保留了大量老旧的 .NET 3.5 兼容层默认建议的 API 兼容级别是 .NET Standard 2.0 和 .NET 4.x这意味着可以使用更多现代 C# 语法和框架类型。而 VS2017 虽然老但只要补丁打到 15.9 以上配合 Unity 2020 开发时无论是 MonoBehaviour 脚本模板、断点调试还是 Unity 类库智能提示都正常流畅。换句话说这对组合不需要额外装 VS2019 或 VS2022 也能开发调试。有一点要明白VS 在这里只是编写代码和调试 C# 脚本的工具真正的运行时依赖来自 Unity 自带的 Mono 或 IL2CPP 运行时以及你放进项目的 MySql.Data.dll。因为 Unity 的托管运行时会用一个固定的加载器识别程序集所以版本兼容问题的核心在于MySql.Data 这个程序集编译时针对的是哪个 .NET 版本是否和你工程中设定的 API Compatibility Level 匹配。我实际测试下来最稳的组合是这样的Unity 2020.3.xVS2017 15.9 及以上MySQL 5.7 或 8.0本地库或远程库均可MySQL Connector/NET 6.9.9 或 8.0.181.2 为什么选 MySQL 而不是 SQLite 或其它先聊一个容易纠结的问题Unity 本地持久化用 SQLite 不香吗确实如果是纯单机、数据量小、逻辑简单的场景SQLite 很合适。但一旦出现多人共享同一份数据、后台需要同步分析、或者客户端崩溃后数据仍然要保留在服务端那么 SQLite 就力不从心了。MySQL 在这类场景里的定位更像一个独立的“数据仓库”客户端通过 TCP 协议把 SQL 语句发到 MySQL 服务端由服务端解析执行后返回结果。Unity 直连 MySQL 意味着可以在编辑器菜单里直接往库里搬数据也可以在游戏内部做一个管理界面甚至可以做存档同步的雏形。这种直连方案本身不复杂复杂度主要来自连接稳定性和程序集兼容性。1.3 技术栈全景整套链路如下Unity 游戏引擎负责场景渲染、UI 展示、用户交互C# 脚本通过 MySql.Data.dll 提供的 ADO.NET 接口发起数据库操作MySQL 服务端接收 SQL 语句执行数据读写VS2017负责写代码、调试断点数据流向很简单Unity 脚本 - MySqlConnection - 网络 - MySQL Server - 返回结果集 - Unity 处理并刷新 UI。很多教程只告诉你“放一个 DLL、写一段代码”但这只解决了一个点。真正的工程化落地要把版本匹配、错误分类、异常兜底、异步优化都考虑到否则只能算“偶尔能跑通”。2. 环境准备与关键资源2.1 基础软件安装在你开始贴代码之前请先检查下面几个环境项缺任何一个都会在运行时暴雷。第一VS2017 必须升级到 15.9.x。只装初始版的 VS2017 缺少对 Unity 2020 的接口适配打开脚本文件时可能不识别 Unity API断点调试也会失效。升级很简单去 Visual Studio Installer 中更新即可。第二Unity 2020.3 安装时建议勾选 Windows Build Support (IL2CPP) 和 .NET 4.x 支持。其实 Unity 2020 对 .NET 4.x 的支持默认就是开启的但如果你在 Player Settings 中手动调低到 .NET Standard 2.0部分 MySql.Data 的接口可能不可用。第三MySQL 服务端建议安装 5.7 或 8.0 版本。如果只是本地开发用默认的 root 账号无非就是防火墙和密码加密规则两个坑后面会讲。生产环境建议单独建账号。2.2 下载 MySQL Connector/NET这是最容易踩坑的环节。Connector/NET 分很多版本Unity 并不能直接兼容所有版本。我的建议是如果你选择 MySQL 8.0下载 Connector/NET 8.0.18 或相近版本如果你选择 MySQL 5.7直接用 Connector/NET 6.9.9为什么选 8.0.18因为从 Connector/NET 8.0.x 开始默认的认证协议变成了 caching_sha2_password老版本的 MySql.Data.dll 根本不认识这个协议一连接就报错。8.0.18 之后的一些版本虽然功能更多但在 Unity 的 Mono 环境下偶发反射或加载问题。所以锁定 8.0.18 是最省心的。下载时不要选 Installer选 Zip 包因为只需要里面的 DLL 文件不需要全局安装。解压后找这几个关键文件MySql.Data.dll依赖的 Google.Protobuf.dll8.0 版本需要System.Buffers.dll 等如果目标框架需要实际需要的依赖数量取决于你当前的 API Level后面第 3 节会说明怎么判断。2.3 准备一个测试数据库和表打开命令行或图形工具执行这一段 SQL建一个后续测试用的库和表CREATE DATABASE IF NOT EXISTS unity_test CHARACTER SET utf8mb4; USE unity_test; CREATE TABLE IF NOT EXISTS player ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, score INT DEFAULT 0, login_time DATETIME DEFAULT CURRENT_TIMESTAMP ); INSERT INTO player (name, score) VALUES (A, 100); INSERT INTO player (name, score) VALUES (B, 200);这一步的意义是用最小的数据量验证链路通不通。实际项目中表结构会更复杂但测试阶段越简单越好。3. 核心细节DLL 引入与兼容性配置3.1 DLL 必须放进 Assets/Plugins很多人喜欢把 MySql.Data.dll 放在 Assets 根目录或者放在某个子目录里。这在编辑器里有时能跑但一旦打包或者做 iOS/Android 构建就会出现找不到类型或者程序集加载失败。正确做法是放在Assets/Plugins下Assets/ └── Plugins/ ├── MySql.Data.dll ├── Google.Protobuf.dll └── System.Buffers.dllPlugins 目录是 Unity 的固定查找目录程序集在打包时会按平台自动处理。如果你的项目未来还要打包到 Android注意在 Plugins 里给 Android 平台设置独立的 DLL 导入设置否则默认可能被排除。顺手提醒一下不要直接把整个 MySQL Connector 目录拷贝进来里面包含大量无关 DLL 和 XML 注释文件会增加程序集加载的反射开销。只保留运行期必须的那几个。3.2 Player Settings 的 API Compatibility Level这个配置位于Edit - Project Settings - Player - Other Settings - Configuration - Api Compatibility Level。Unity 2020 提供两个主要选项.NET Standard 2.0.NET 4.x如果你选 .NET Standard 2.0那么 MySql.Data 8.0.x 大概率能跑但某些 API比如完整 DataSet 支持会被削弱。我实际测试下来用 .NET 4.x 最省事因为 Connector/NET 针对 .NET Framework 编译的核心路径在 Mono 下兼容性最好。3.3 为什么版本匹配这么敏感我们打个比方MySql.Data.dll 相当于一份“翻译手册”Unity 里的 C# 脚本要靠它翻译成 MySQL 听得懂的 TCP 数据包。如果翻译手册里用了 Unity 不认识的语法比如更高版本的 .NET APIUnity 加载时就罢工表现就是找不到命名空间、类型加载失败、或者运行时抛TypeLoadException。所以在决定 Connector 版本之前先确认两件事Unity 设置的 API Level目标 MySQL 服务端的认证协议这两个点决定了你要用哪个版本的 DLL以及需要补哪些依赖。3.4 连接字符串的正确写法连接数据库的入口是 MySqlConnection关键在于 ConnectionString。最基础但稳妥的格式是Server127.0.0.1;Port3306;Databaseunity_test;User Idroot;Password你的密码;Charsetutf8;Connection Timeout5;几个参数的解释Server建议写 127.0.0.1不要写 localhost。在部分系统上 localhost 可能被解析成 IPv6 的 ::1而 MySQL 没有监听 IPv6导致连接直接超时Port默认 3306如果服务端改过端口就要同步Charsetutf8防止中文乱码Connection Timeout建议给 5 秒或更短避免数据库不可达时 Unity 卡住4. 实操过程从连接测试到常见操作4.1 第一个脚本连接测试创建一个 C# 脚本MySqlConnectionTest.cs然后丢到场景里的任意物体上。在编辑器里直接运行看到日志输出就算成功。using System; using UnityEngine; using MySql.Data.MySqlClient; public class MySqlConnectionTest : MonoBehaviour { private void Start() { string connStr Server127.0.0.1;Port3306;Databaseunity_test;User Idroot;Password你的密码;Charsetutf8;Connection Timeout5;; using (MySqlConnection conn new MySqlConnection(connStr)) { try { conn.Open(); Debug.Log(连接成功); } catch (Exception ex) { Debug.LogError(连接失败: ex.Message); } } } }这里重点注意using语句。ADO.NET 的连接资源是有限且昂贵的用完一定要释放。用using能保证连接对象在作用域结束时自动调用 Dispose避免数据库连接泄漏。我第一次跑这个脚本时卡在了MySql.Data.MySqlClient找不到命名空间。原因就是 DLL 放在了 Assets 根目录但因为某些导入设置没生效。后来移进 Plugins 才稳定。4.2 增强版封装一个 DbManager连接测试通过后接着别急着写一大堆 SQL先封装一个简单的数据库管理器。这个类可以在任何脚本里复用。using System; using System.Data; using UnityEngine; using MySql.Data.MySqlClient; public class DbManager { private string connectionString; public DbManager(string server, string database, string user, string password, int port 3306) { connectionString string.Format( Server{0};Port{1};Database{2};User Id{3};Password{4};Charsetutf8;Connection Timeout5;, server, port, database, user, password); } public DataTable Query(string sql) { DataTable dt new DataTable(); try { using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) using (MySqlDataAdapter adapter new MySqlDataAdapter(cmd)) { adapter.Fill(dt); } } } catch (Exception ex) { Debug.LogError(查询出错: ex.Message); } return dt; } public int ExecuteNonQuery(string sql) { int affected 0; try { using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) { affected cmd.ExecuteNonQuery(); } } } catch (Exception ex) { Debug.LogError(执行出错: ex.Message); } return affected; } }这里有意用了DataTable和MySqlDataAdapter方便后面直接绑定 UI 数据源。如果只是想读取单值可以用cmd.ExecuteScalar()省掉 DataTable 的开销。4.3 数据读取与 UI 展示为了验证链路我习惯做一个极简 UI在场景里放一个 Text 和一个 Button点击按钮后把 player 表查询结果显示在面板上。using UnityEngine; using UnityEngine.UI; public class DataPanel : MonoBehaviour { public Text resultText; private DbManager db; private void Start() { db new DbManager(127.0.0.1, unity_test, root, 你的密码); } public void OnClickLoadData() { DataTable table db.Query(SELECT name, score FROM player ORDER BY score DESC); if (table null || table.Rows.Count 0) { resultText.text 暂无数据; return; } string display ; foreach (DataRow row in table.Rows) { display row[name] row[score] \n; } resultText.text display; } }Button 的 onClick 事件直接在 Unity 编辑器里拖绑定即可。这一步做完说明 Unity 与 MySQL 的数据链路已经完全打通点击按钮 - 发起 SQL - MySQL 执行 - 返回结果 - UI 刷新。有一个容易忽略的细节Text 里显示中文时如果出现乱码先检查 MySQL 表本身的数据编码再确认连接串里的 Charset 是否等于 utf8最后看场景字体是否缺失中文字形这三点按顺序排查。4.4 增删改操作示例光查询还不够实际项目肯定要写数据。举个例子模拟玩家得分更新的操作public void AddPlayerScore(string name, int addScore) { int newScore 0; object result db.ExecuteScalar(SELECT score FROM player WHERE name name ); if (result ! null result ! DBNull.Value) { newScore Convert.ToInt32(result) addScore; } string sql UPDATE player SET score newScore WHERE name name ; db.ExecuteNonQuery(sql); }先别急着学这段写法我在第 6 节会重点强调 SQL 注入的问题。上面的拼接字符串仅在内部测试时使用任何面向外部输入的功能都不要这么写要用参数化查询。增删改的通用套路就三步拼 SQL、构造 MySqlCommand、调用 ExecuteNonQuery。这里我补充一个带参数的正确示例public void UpdateScore(string name, int addScore) { string sql UPDATE player SET score score addScore WHERE name name; using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) { cmd.Parameters.AddWithValue(addScore, addScore); cmd.Parameters.AddWithValue(name, name); cmd.ExecuteNonQuery(); } } }两者一比就明白了参数化之后特殊字符不会被当成 SQL 语句执行传什么都是纯数据。这是底线不要省。4.5 编辑器菜单快速测试有时候你不想启动游戏只想在编辑器里点个按钮验证数据库连通性。我给 DbManager 加了一个编辑器测试入口#if UNITY_EDITOR using UnityEditor; public static class DbEditorTool { [MenuItem(Tools/Test MySQL)] public static void TestConnection() { DbManager db new DbManager(127.0.0.1, unity_test, root, 你的密码); DataTable dt db.Query(SELECT COUNT(*) AS total FROM player); Debug.Log(当前记录数: dt.Rows[0][total]); } } #endif这样不用进 Play Mode直接在 Unity 菜单栏点Tools - Test MySQL就能看到结果。开发阶段排查数据库问题时效率极高。5. 踩坑实录常见问题与排查技巧这一节是我最想写的部分。因为这套组合的连接错误五花八门但我梳理下来基本只有六类每一类都有对应的排查路径。5.1 “找不到 MySql.Data” 或 “命名空间不存在”现象代码里using MySql.Data.MySqlClient;一行标红或者编译报错。原因DLL 没被正确加载。最常见的是 DLL 不在 Plugins 目录或者 DLL 的导入设置被 Unity 排除。排查在 Project 窗口选中 MySql.Data.dll查看 Inspector 里的 Platform Settings确保 Editor 和 Standalone 平台都是勾选状态。解决把它移入 Assets/Plugins并重启 Unity。5.2 认证协议报错现象运行时报如下错误Authentication method caching_sha2_password not supported原因MySQL 8.0 默认使用 caching_sha2_password 认证协议而你使用的 MySql.Data 版本太老或者没启用对应支持。解决方案一换用 Connector/NET 8.0.18方案二在 MySQL 里把当前用户的认证协议改成 mysql_native_passwordALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;我记得当时顺手测过两种方案最终在项目里选了 Connector 版本对齐而不是改认证协议因为改老协议在集群迁移时会有额外兼容成本。5.3 连接超时现象connect timeout expired或者Unable to connect to any of the specified MySQL hosts原因网络不通、IP 错误、端口错误、服务端没启动、防火墙拦截。排查步骤先确认服务端 MySQL 服务已启动在同机命令行执行ping 127.0.0.1确认网络栈正常用telnet 127.0.0.1 3306测试端口连通性如果远程连接检查服务端是否绑定了对外 IP以及防火墙 3306 端口是否放行在连接串中把 Server 换成 127.0.0.1 而不是 localhost5.4 中文乱码现象数据库里中文正常但读到 Unity 显示成乱码或者写入的中文变成问号。原因连接串未指定 Charset或者表结构本身不是 utf8/utf8mb4。解决连接串加Charsetutf8;建表时用CHARACTER SET utf8mb4。MySQL 8.0 默认就是 utf8mb4通常不会出问题但 5.7 的默认可能是 latin1。5.5 打包后无法运行现象编辑器里一切正常但打包成 exe 后点击功能无响应日志提示找不到程序集。原因MySql.Data.dll 及依赖 DLL 没有随构建产物打包或 SDK 平台选错。解决确认所有 DLL 在 Assets/Plugins 下然后在 Player Settings 里查看每个插件的 Platform 设置勾选需要支持的平台并确认Any Platform开启。重新构建并运行一次把日志路径打开看看有没有加载失败的记录。5.6 Unity 主线程卡顿现象大量数据查询时画面掉帧严重甚至整个窗口无响应。原因数据库操作是同步阻塞的在 OnGUI 或 Update 里经常调用就会卡住主线程。解决把耗时操作放到协程或线程池。协程依然跑在主线程但至少允许一帧一帧返回配合 Timeout 不会造成无限制阻塞线程池能彻底避免阻塞主线程但要注意 Unity API 只能在主线程访问所以线程池里只做数据读取拿到结果后再转回主线程更新 UI。简单给一个协程版封装示意public IEnumerator QueryAsync(string sql, ActionDataTable onComplete) { DataTable dt null; bool done false; new Thread(() { dt db.Query(sql); done true; }).Start(); while (!done) { yield return null; } if (onComplete ! null) { onComplete(dt); } }用线程时DataTable 的构造和填充都在后台线程完成主线程只接管结果这种方法我试过多次在数据量几百到几千行时都很稳定。6. 性能优化与安全加固6.1 连接复用和连接池直连 MySQL 时每次 Open 和 Close 在底层都涉及 TCP 握手。如果频繁操作性能会非常难看。但 ADO.NET 默认开着连接池同一个连接字符串会自动复用连接所以理论上不需要手动缓存连接对象。不过有个隐性坑连接池会保持空闲连接如果 MySQL 服务端 wait_timeout 小于你的任务间隔连接会被服务端掐断。此时再使用池中的连接会抛 “Packet out of order” 之类诡异错误。解决方法是设置Poolingtrue;并给连接加Connection Lifetime参数或者捕获到连接异常后重试一次。最简单粗暴的做法是每次操作都新建 MySqlConnection 对象依赖连接池出现断连错误时先清空连接池再重试。6.2 编辑器运行时的频繁调用如果你在编辑器里做了一个实时刷新数据的窗口千万别在 Update 里每帧查库。建议做一个刷新间隔控制比如至少 1 秒才查一次或者干脆只在用户操作的时候才查。数据库不是为游戏主循环设计的每帧查询是给自己找麻烦。6.3 使用参数化查询这部分再怎么强调都不过分。SQL 注入的经典场景就是把用户输入直接拼进 SQL 字符串里比如string sql SELECT * FROM player WHERE name input ;只要 input 传入 OR 11整张表就会暴露。正确写法是所有外部变量都用参数传入string sql SELECT * FROM player WHERE name name; cmd.Parameters.AddWithValue(name, input);这是底线级的要求跟 Unity 无关任何数据库代码都要默认参数化。6.4 敏感信息不要硬编码数据库密码直接写在脚本里在个人项目里问题不大但只要是多人协作或者做正式发布就必须处理。推荐的简单做法是用 ScriptableObject 存连接配置但不要放进版本控制中把配置做成独立文件如 JSON运行时读取使用时解密或者在编辑器里通过环境变量读取不要出现在代码库中更彻底的做法是建立代理层让 Unity 只访问服务端提供的 API服务端再操作数据库。虽然这样会增加开发量但在安全要求高的场景下这是唯一靠谱的方案。直连方案更适合内部工具、原型验证、局域网管理端这类信任域清晰的应用。6.5 日志与异常处理数据库操作天然容易出错尤其在客户端环境。除了在 DbManager 里捕获异常还要记录足够上下文比如失败的 SQL 语句错误码和异常类型数据库地址和表名这样出现问题后通过日志才能快速定位。另外不要在异常里暴露连接字符串中的密码否则日志文件泄露就风险很大。可以在打印异常前把连接字符串中的 Password 字段替换为***。7. 后续扩展建议这套方案跑通之后你会发现它不只是“Unity 连上了 MySQL”而已。顺着这条链路还能做不少有价值的扩展一是做档案型数据的可视化比如游戏运营后台Unity 里展示用户行为数据、充值记录、关卡进度。与其开发一套网页后台直接用 Unity 编辑器做一个工具窗口会更便捷。二是做配置表的热更新策划在 MySQL 里改数值客户端启动时自动拉取最新配置。配合 ScriptableObject 缓存可以省去频繁发版的麻烦。三是做跨端同步的雏形登录时从库中拉取存档退出时把进度写回。虽然真正上线时不建议客户端直连数据库但作为项目组内部开发和测试工具这套直连方案在开发效率上的优势非常明显。我个人的体会是数据库连接这类技术卡住你的往往不是代码逻辑而是那些藏在版本、协议、路径里的隐性问题。把 DLL 放对、API Level 调对、连接串写对、认证协议配对四关一过剩下的就是写 SQL 的业务活。如果看完这篇还遇到没列到的问题先把异常信息完整打出来多数时候答案就在那三五行报错里。 
长河君 · 2026/10/17 15:16:26 · 阅读 1.2k Unity接入MySQL数据库指南：环境配置、DLL兼容与踩坑实录
做 Unity 项目的时候突然要接数据库第一反应多半是头大。当年我在某个截单工具类项目里遇到同样的需求——Unity 里展示后台记录、保存玩家操作日志、按条件筛选数据这些都是典型的数据持久化场景。而选择“Unity 2020 VS2017 连 MySQL”这套组合当时也是对比了好几轮才定的。先说结论这方案完全可行但坑也不少。最典型的坑就是 MySQL 数据驱动 DLL 的版本兼容问题其次是 Unity 的 API Compatibility Level 配置再就是连接字符串踩出一堆连接失败。这篇文章从头到尾把我实际跑通过的路走一遍从环境选型、DLL 引入、连接配置到完整脚本和常见问题排查全程按照我踩坑之后的正确顺序来讲保证是可复现的实操流程。如果你正在做 Unity 客户端、需要直连 MySQL 做工具类应用或内部管理端或者只是一个想搞明白“Unity 能不能连数据库”的新手这篇能帮你少走至少一个星期的弯路。1. 整体方案设计与选型逻辑1.1 为什么是 Unity 2020 VS2017Unity 2020 是 LTS 版本里的分水岭。它不再像 2018 那样保留了大量老旧的 .NET 3.5 兼容层默认建议的 API 兼容级别是 .NET Standard 2.0 和 .NET 4.x这意味着可以使用更多现代 C# 语法和框架类型。而 VS2017 虽然老但只要补丁打到 15.9 以上配合 Unity 2020 开发时无论是 MonoBehaviour 脚本模板、断点调试还是 Unity 类库智能提示都正常流畅。换句话说这对组合不需要额外装 VS2019 或 VS2022 也能开发调试。有一点要明白VS 在这里只是编写代码和调试 C# 脚本的工具真正的运行时依赖来自 Unity 自带的 Mono 或 IL2CPP 运行时以及你放进项目的 MySql.Data.dll。因为 Unity 的托管运行时会用一个固定的加载器识别程序集所以版本兼容问题的核心在于MySql.Data 这个程序集编译时针对的是哪个 .NET 版本是否和你工程中设定的 API Compatibility Level 匹配。我实际测试下来最稳的组合是这样的Unity 2020.3.xVS2017 15.9 及以上MySQL 5.7 或 8.0本地库或远程库均可MySQL Connector/NET 6.9.9 或 8.0.181.2 为什么选 MySQL 而不是 SQLite 或其它先聊一个容易纠结的问题Unity 本地持久化用 SQLite 不香吗确实如果是纯单机、数据量小、逻辑简单的场景SQLite 很合适。但一旦出现多人共享同一份数据、后台需要同步分析、或者客户端崩溃后数据仍然要保留在服务端那么 SQLite 就力不从心了。MySQL 在这类场景里的定位更像一个独立的“数据仓库”客户端通过 TCP 协议把 SQL 语句发到 MySQL 服务端由服务端解析执行后返回结果。Unity 直连 MySQL 意味着可以在编辑器菜单里直接往库里搬数据也可以在游戏内部做一个管理界面甚至可以做存档同步的雏形。这种直连方案本身不复杂复杂度主要来自连接稳定性和程序集兼容性。1.3 技术栈全景整套链路如下Unity 游戏引擎负责场景渲染、UI 展示、用户交互C# 脚本通过 MySql.Data.dll 提供的 ADO.NET 接口发起数据库操作MySQL 服务端接收 SQL 语句执行数据读写VS2017负责写代码、调试断点数据流向很简单Unity 脚本 - MySqlConnection - 网络 - MySQL Server - 返回结果集 - Unity 处理并刷新 UI。很多教程只告诉你“放一个 DLL、写一段代码”但这只解决了一个点。真正的工程化落地要把版本匹配、错误分类、异常兜底、异步优化都考虑到否则只能算“偶尔能跑通”。2. 环境准备与关键资源2.1 基础软件安装在你开始贴代码之前请先检查下面几个环境项缺任何一个都会在运行时暴雷。第一VS2017 必须升级到 15.9.x。只装初始版的 VS2017 缺少对 Unity 2020 的接口适配打开脚本文件时可能不识别 Unity API断点调试也会失效。升级很简单去 Visual Studio Installer 中更新即可。第二Unity 2020.3 安装时建议勾选 Windows Build Support (IL2CPP) 和 .NET 4.x 支持。其实 Unity 2020 对 .NET 4.x 的支持默认就是开启的但如果你在 Player Settings 中手动调低到 .NET Standard 2.0部分 MySql.Data 的接口可能不可用。第三MySQL 服务端建议安装 5.7 或 8.0 版本。如果只是本地开发用默认的 root 账号无非就是防火墙和密码加密规则两个坑后面会讲。生产环境建议单独建账号。2.2 下载 MySQL Connector/NET这是最容易踩坑的环节。Connector/NET 分很多版本Unity 并不能直接兼容所有版本。我的建议是如果你选择 MySQL 8.0下载 Connector/NET 8.0.18 或相近版本如果你选择 MySQL 5.7直接用 Connector/NET 6.9.9为什么选 8.0.18因为从 Connector/NET 8.0.x 开始默认的认证协议变成了 caching_sha2_password老版本的 MySql.Data.dll 根本不认识这个协议一连接就报错。8.0.18 之后的一些版本虽然功能更多但在 Unity 的 Mono 环境下偶发反射或加载问题。所以锁定 8.0.18 是最省心的。下载时不要选 Installer选 Zip 包因为只需要里面的 DLL 文件不需要全局安装。解压后找这几个关键文件MySql.Data.dll依赖的 Google.Protobuf.dll8.0 版本需要System.Buffers.dll 等如果目标框架需要实际需要的依赖数量取决于你当前的 API Level后面第 3 节会说明怎么判断。2.3 准备一个测试数据库和表打开命令行或图形工具执行这一段 SQL建一个后续测试用的库和表CREATE DATABASE IF NOT EXISTS unity_test CHARACTER SET utf8mb4; USE unity_test; CREATE TABLE IF NOT EXISTS player ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, score INT DEFAULT 0, login_time DATETIME DEFAULT CURRENT_TIMESTAMP ); INSERT INTO player (name, score) VALUES (A, 100); INSERT INTO player (name, score) VALUES (B, 200);这一步的意义是用最小的数据量验证链路通不通。实际项目中表结构会更复杂但测试阶段越简单越好。3. 核心细节DLL 引入与兼容性配置3.1 DLL 必须放进 Assets/Plugins很多人喜欢把 MySql.Data.dll 放在 Assets 根目录或者放在某个子目录里。这在编辑器里有时能跑但一旦打包或者做 iOS/Android 构建就会出现找不到类型或者程序集加载失败。正确做法是放在Assets/Plugins下Assets/ └── Plugins/ ├── MySql.Data.dll ├── Google.Protobuf.dll └── System.Buffers.dllPlugins 目录是 Unity 的固定查找目录程序集在打包时会按平台自动处理。如果你的项目未来还要打包到 Android注意在 Plugins 里给 Android 平台设置独立的 DLL 导入设置否则默认可能被排除。顺手提醒一下不要直接把整个 MySQL Connector 目录拷贝进来里面包含大量无关 DLL 和 XML 注释文件会增加程序集加载的反射开销。只保留运行期必须的那几个。3.2 Player Settings 的 API Compatibility Level这个配置位于Edit - Project Settings - Player - Other Settings - Configuration - Api Compatibility Level。Unity 2020 提供两个主要选项.NET Standard 2.0.NET 4.x如果你选 .NET Standard 2.0那么 MySql.Data 8.0.x 大概率能跑但某些 API比如完整 DataSet 支持会被削弱。我实际测试下来用 .NET 4.x 最省事因为 Connector/NET 针对 .NET Framework 编译的核心路径在 Mono 下兼容性最好。3.3 为什么版本匹配这么敏感我们打个比方MySql.Data.dll 相当于一份“翻译手册”Unity 里的 C# 脚本要靠它翻译成 MySQL 听得懂的 TCP 数据包。如果翻译手册里用了 Unity 不认识的语法比如更高版本的 .NET APIUnity 加载时就罢工表现就是找不到命名空间、类型加载失败、或者运行时抛TypeLoadException。所以在决定 Connector 版本之前先确认两件事Unity 设置的 API Level目标 MySQL 服务端的认证协议这两个点决定了你要用哪个版本的 DLL以及需要补哪些依赖。3.4 连接字符串的正确写法连接数据库的入口是 MySqlConnection关键在于 ConnectionString。最基础但稳妥的格式是Server127.0.0.1;Port3306;Databaseunity_test;User Idroot;Password你的密码;Charsetutf8;Connection Timeout5;几个参数的解释Server建议写 127.0.0.1不要写 localhost。在部分系统上 localhost 可能被解析成 IPv6 的 ::1而 MySQL 没有监听 IPv6导致连接直接超时Port默认 3306如果服务端改过端口就要同步Charsetutf8防止中文乱码Connection Timeout建议给 5 秒或更短避免数据库不可达时 Unity 卡住4. 实操过程从连接测试到常见操作4.1 第一个脚本连接测试创建一个 C# 脚本MySqlConnectionTest.cs然后丢到场景里的任意物体上。在编辑器里直接运行看到日志输出就算成功。using System; using UnityEngine; using MySql.Data.MySqlClient; public class MySqlConnectionTest : MonoBehaviour { private void Start() { string connStr Server127.0.0.1;Port3306;Databaseunity_test;User Idroot;Password你的密码;Charsetutf8;Connection Timeout5;; using (MySqlConnection conn new MySqlConnection(connStr)) { try { conn.Open(); Debug.Log(连接成功); } catch (Exception ex) { Debug.LogError(连接失败: ex.Message); } } } }这里重点注意using语句。ADO.NET 的连接资源是有限且昂贵的用完一定要释放。用using能保证连接对象在作用域结束时自动调用 Dispose避免数据库连接泄漏。我第一次跑这个脚本时卡在了MySql.Data.MySqlClient找不到命名空间。原因就是 DLL 放在了 Assets 根目录但因为某些导入设置没生效。后来移进 Plugins 才稳定。4.2 增强版封装一个 DbManager连接测试通过后接着别急着写一大堆 SQL先封装一个简单的数据库管理器。这个类可以在任何脚本里复用。using System; using System.Data; using UnityEngine; using MySql.Data.MySqlClient; public class DbManager { private string connectionString; public DbManager(string server, string database, string user, string password, int port 3306) { connectionString string.Format( Server{0};Port{1};Database{2};User Id{3};Password{4};Charsetutf8;Connection Timeout5;, server, port, database, user, password); } public DataTable Query(string sql) { DataTable dt new DataTable(); try { using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) using (MySqlDataAdapter adapter new MySqlDataAdapter(cmd)) { adapter.Fill(dt); } } } catch (Exception ex) { Debug.LogError(查询出错: ex.Message); } return dt; } public int ExecuteNonQuery(string sql) { int affected 0; try { using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) { affected cmd.ExecuteNonQuery(); } } } catch (Exception ex) { Debug.LogError(执行出错: ex.Message); } return affected; } }这里有意用了DataTable和MySqlDataAdapter方便后面直接绑定 UI 数据源。如果只是想读取单值可以用cmd.ExecuteScalar()省掉 DataTable 的开销。4.3 数据读取与 UI 展示为了验证链路我习惯做一个极简 UI在场景里放一个 Text 和一个 Button点击按钮后把 player 表查询结果显示在面板上。using UnityEngine; using UnityEngine.UI; public class DataPanel : MonoBehaviour { public Text resultText; private DbManager db; private void Start() { db new DbManager(127.0.0.1, unity_test, root, 你的密码); } public void OnClickLoadData() { DataTable table db.Query(SELECT name, score FROM player ORDER BY score DESC); if (table null || table.Rows.Count 0) { resultText.text 暂无数据; return; } string display ; foreach (DataRow row in table.Rows) { display row[name] row[score] \n; } resultText.text display; } }Button 的 onClick 事件直接在 Unity 编辑器里拖绑定即可。这一步做完说明 Unity 与 MySQL 的数据链路已经完全打通点击按钮 - 发起 SQL - MySQL 执行 - 返回结果 - UI 刷新。有一个容易忽略的细节Text 里显示中文时如果出现乱码先检查 MySQL 表本身的数据编码再确认连接串里的 Charset 是否等于 utf8最后看场景字体是否缺失中文字形这三点按顺序排查。4.4 增删改操作示例光查询还不够实际项目肯定要写数据。举个例子模拟玩家得分更新的操作public void AddPlayerScore(string name, int addScore) { int newScore 0; object result db.ExecuteScalar(SELECT score FROM player WHERE name name ); if (result ! null result ! DBNull.Value) { newScore Convert.ToInt32(result) addScore; } string sql UPDATE player SET score newScore WHERE name name ; db.ExecuteNonQuery(sql); }先别急着学这段写法我在第 6 节会重点强调 SQL 注入的问题。上面的拼接字符串仅在内部测试时使用任何面向外部输入的功能都不要这么写要用参数化查询。增删改的通用套路就三步拼 SQL、构造 MySqlCommand、调用 ExecuteNonQuery。这里我补充一个带参数的正确示例public void UpdateScore(string name, int addScore) { string sql UPDATE player SET score score addScore WHERE name name; using (MySqlConnection conn new MySqlConnection(connectionString)) { conn.Open(); using (MySqlCommand cmd new MySqlCommand(sql, conn)) { cmd.Parameters.AddWithValue(addScore, addScore); cmd.Parameters.AddWithValue(name, name); cmd.ExecuteNonQuery(); } } }两者一比就明白了参数化之后特殊字符不会被当成 SQL 语句执行传什么都是纯数据。这是底线不要省。4.5 编辑器菜单快速测试有时候你不想启动游戏只想在编辑器里点个按钮验证数据库连通性。我给 DbManager 加了一个编辑器测试入口#if UNITY_EDITOR using UnityEditor; public static class DbEditorTool { [MenuItem(Tools/Test MySQL)] public static void TestConnection() { DbManager db new DbManager(127.0.0.1, unity_test, root, 你的密码); DataTable dt db.Query(SELECT COUNT(*) AS total FROM player); Debug.Log(当前记录数: dt.Rows[0][total]); } } #endif这样不用进 Play Mode直接在 Unity 菜单栏点Tools - Test MySQL就能看到结果。开发阶段排查数据库问题时效率极高。5. 踩坑实录常见问题与排查技巧这一节是我最想写的部分。因为这套组合的连接错误五花八门但我梳理下来基本只有六类每一类都有对应的排查路径。5.1 “找不到 MySql.Data” 或 “命名空间不存在”现象代码里using MySql.Data.MySqlClient;一行标红或者编译报错。原因DLL 没被正确加载。最常见的是 DLL 不在 Plugins 目录或者 DLL 的导入设置被 Unity 排除。排查在 Project 窗口选中 MySql.Data.dll查看 Inspector 里的 Platform Settings确保 Editor 和 Standalone 平台都是勾选状态。解决把它移入 Assets/Plugins并重启 Unity。5.2 认证协议报错现象运行时报如下错误Authentication method caching_sha2_password not supported原因MySQL 8.0 默认使用 caching_sha2_password 认证协议而你使用的 MySql.Data 版本太老或者没启用对应支持。解决方案一换用 Connector/NET 8.0.18方案二在 MySQL 里把当前用户的认证协议改成 mysql_native_passwordALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;我记得当时顺手测过两种方案最终在项目里选了 Connector 版本对齐而不是改认证协议因为改老协议在集群迁移时会有额外兼容成本。5.3 连接超时现象connect timeout expired或者Unable to connect to any of the specified MySQL hosts原因网络不通、IP 错误、端口错误、服务端没启动、防火墙拦截。排查步骤先确认服务端 MySQL 服务已启动在同机命令行执行ping 127.0.0.1确认网络栈正常用telnet 127.0.0.1 3306测试端口连通性如果远程连接检查服务端是否绑定了对外 IP以及防火墙 3306 端口是否放行在连接串中把 Server 换成 127.0.0.1 而不是 localhost5.4 中文乱码现象数据库里中文正常但读到 Unity 显示成乱码或者写入的中文变成问号。原因连接串未指定 Charset或者表结构本身不是 utf8/utf8mb4。解决连接串加Charsetutf8;建表时用CHARACTER SET utf8mb4。MySQL 8.0 默认就是 utf8mb4通常不会出问题但 5.7 的默认可能是 latin1。5.5 打包后无法运行现象编辑器里一切正常但打包成 exe 后点击功能无响应日志提示找不到程序集。原因MySql.Data.dll 及依赖 DLL 没有随构建产物打包或 SDK 平台选错。解决确认所有 DLL 在 Assets/Plugins 下然后在 Player Settings 里查看每个插件的 Platform 设置勾选需要支持的平台并确认Any Platform开启。重新构建并运行一次把日志路径打开看看有没有加载失败的记录。5.6 Unity 主线程卡顿现象大量数据查询时画面掉帧严重甚至整个窗口无响应。原因数据库操作是同步阻塞的在 OnGUI 或 Update 里经常调用就会卡住主线程。解决把耗时操作放到协程或线程池。协程依然跑在主线程但至少允许一帧一帧返回配合 Timeout 不会造成无限制阻塞线程池能彻底避免阻塞主线程但要注意 Unity API 只能在主线程访问所以线程池里只做数据读取拿到结果后再转回主线程更新 UI。简单给一个协程版封装示意public IEnumerator QueryAsync(string sql, ActionDataTable onComplete) { DataTable dt null; bool done false; new Thread(() { dt db.Query(sql); done true; }).Start(); while (!done) { yield return null; } if (onComplete ! null) { onComplete(dt); } }用线程时DataTable 的构造和填充都在后台线程完成主线程只接管结果这种方法我试过多次在数据量几百到几千行时都很稳定。6. 性能优化与安全加固6.1 连接复用和连接池直连 MySQL 时每次 Open 和 Close 在底层都涉及 TCP 握手。如果频繁操作性能会非常难看。但 ADO.NET 默认开着连接池同一个连接字符串会自动复用连接所以理论上不需要手动缓存连接对象。不过有个隐性坑连接池会保持空闲连接如果 MySQL 服务端 wait_timeout 小于你的任务间隔连接会被服务端掐断。此时再使用池中的连接会抛 “Packet out of order” 之类诡异错误。解决方法是设置Poolingtrue;并给连接加Connection Lifetime参数或者捕获到连接异常后重试一次。最简单粗暴的做法是每次操作都新建 MySqlConnection 对象依赖连接池出现断连错误时先清空连接池再重试。6.2 编辑器运行时的频繁调用如果你在编辑器里做了一个实时刷新数据的窗口千万别在 Update 里每帧查库。建议做一个刷新间隔控制比如至少 1 秒才查一次或者干脆只在用户操作的时候才查。数据库不是为游戏主循环设计的每帧查询是给自己找麻烦。6.3 使用参数化查询这部分再怎么强调都不过分。SQL 注入的经典场景就是把用户输入直接拼进 SQL 字符串里比如string sql SELECT * FROM player WHERE name input ;只要 input 传入 OR 11整张表就会暴露。正确写法是所有外部变量都用参数传入string sql SELECT * FROM player WHERE name name; cmd.Parameters.AddWithValue(name, input);这是底线级的要求跟 Unity 无关任何数据库代码都要默认参数化。6.4 敏感信息不要硬编码数据库密码直接写在脚本里在个人项目里问题不大但只要是多人协作或者做正式发布就必须处理。推荐的简单做法是用 ScriptableObject 存连接配置但不要放进版本控制中把配置做成独立文件如 JSON运行时读取使用时解密或者在编辑器里通过环境变量读取不要出现在代码库中更彻底的做法是建立代理层让 Unity 只访问服务端提供的 API服务端再操作数据库。虽然这样会增加开发量但在安全要求高的场景下这是唯一靠谱的方案。直连方案更适合内部工具、原型验证、局域网管理端这类信任域清晰的应用。6.5 日志与异常处理数据库操作天然容易出错尤其在客户端环境。除了在 DbManager 里捕获异常还要记录足够上下文比如失败的 SQL 语句错误码和异常类型数据库地址和表名这样出现问题后通过日志才能快速定位。另外不要在异常里暴露连接字符串中的密码否则日志文件泄露就风险很大。可以在打印异常前把连接字符串中的 Password 字段替换为***。7. 后续扩展建议这套方案跑通之后你会发现它不只是“Unity 连上了 MySQL”而已。顺着这条链路还能做不少有价值的扩展一是做档案型数据的可视化比如游戏运营后台Unity 里展示用户行为数据、充值记录、关卡进度。与其开发一套网页后台直接用 Unity 编辑器做一个工具窗口会更便捷。二是做配置表的热更新策划在 MySQL 里改数值客户端启动时自动拉取最新配置。配合 ScriptableObject 缓存可以省去频繁发版的麻烦。三是做跨端同步的雏形登录时从库中拉取存档退出时把进度写回。虽然真正上线时不建议客户端直连数据库但作为项目组内部开发和测试工具这套直连方案在开发效率上的优势非常明显。我个人的体会是数据库连接这类技术卡住你的往往不是代码逻辑而是那些藏在版本、协议、路径里的隐性问题。把 DLL 放对、API Level 调对、连接串写对、认证协议配对四关一过剩下的就是写 SQL 的业务活。如果看完这篇还遇到没列到的问题先把异常信息完整打出来多数时候答案就在那三五行报错里。