Unity连接MySQL显示表格：Simple TableUI完整实现与踩坑指南

简介面向需要在Unity中接入MySQL的开发者尤其适合正在制作角色数据、排行榜、后台配置等界面需要动态读取数据库并展示表格的场景。基于Unity 2020.3.45f1完整演示了从数据库连接、数据查询到利用Simple TableUI生成表格显示的全过程并针对该插件常见的初始化报错、数据绑定失败等问题给出了具体的解决指引。压缩包为zip格式整体约24.36MB因上游未解析文件明细包内具体文件数与类型暂未列出但可确定内容核心是可直接对照使用的示例工程与脚本主体为C#脚本、Unity场景及插件配置。目前已有743人学习/下载资源内提供了可复用的连接逻辑与排错思路能显著减少环境搭建和调试时间适合有一定C#基础、希望快速实现MySQL数据表格展示的Unity工程人员。1. Unity 连接 MySQL 显示表格先搞清楚这套链路在解决什么问题Unity 连接 MySQL 显示表格Simple TableUI这个需求本质上是把 MySQL 里的关系表搬到 Unity 的 UI 上做成一个可滚动、可对齐、可刷新的表格控件。做管理后台、数据看板、运营工具这类项目时很多人不想再起一套 Web 前端直接在 Unity 里连库、查数、渲染列表省掉中间服务这也是 Simple TableUI 这类轻量方案存在的理由。但这套链路远比连上就完事复杂驱动 DLL 要和 Unity 的 API 兼容级别匹配查询动作不能卡主线程读回来的字段类型要做二次转换TINYINT(1) 会变成布尔值DATETIME 自带时区中文还可能全员变问号。这篇笔记把整条链路走一遍——环境选型、连接串、查数封装、TableUI 生成与滚动复用每步给能直接抄的代码和参数最后是五条高频踩坑记录。适合要用 Unity 做内部工具、数据看板或者想把数据表格嵌进游戏运营界面的开发者新手能照着跑通熟手可以直接拿走排错清单。2. 环境准备与踩坑前置Unity 版本、MySQL 驱动与 .NET 兼容性2.1 为什么 Unity 连 MySQL 总在第一步翻车程序集与 API 兼容级别最常见的失败不是 SQL 写错而是第一步就过不去从网上找了个 DLL 丢进 Assets 后编译直接报错或者运行时抛TypeInitializationException连new MySqlConnection()都走不到。根因基本都出在 Unity 的 API 兼容级别和驱动程序集的 .NET 目标框架不匹配。Unity 项目里有一个选项叫 API Compatibility Level常见取值是.NET Framework 4.x和.NET Standard 2.1。老版本的官方驱动 MySql.DataConnector/NET如果编译目标是老 .NET Framework那么在.NET Standard 2.1级别下经常会加载不出类型反过来新版驱动在.NET Framework 4.x下也可能因为引用了不存在的程序集直接初始化失败。我的习惯是先看项目 Player Settings 里当前用的是哪个级别再决定驱动怎么选。我一般会优先用 MySqlConnector 这个纯托管实现它对 .NET Standard 的支持更干净运行时依赖少IL2CPP 打包时被剪裁误伤的概率也小。选型的另一个判断点是认证插件MySQL 8.0 默认用的caching_sha2_password老版 MySql.Data 根本不会认证一连就报Authentication to host failed。如果你因为历史原因只能用官方驱动就要把版本换到支持该插件的较新版本或者把数据库账号改回兼容的认证方式。还有一个常见的低级坑DLL 在 Assets 里出现两份。有人把驱动放在Assets/Plugins又为了保险在根目录也丢了一份结果编辑器里跑的是 A 版本打包时编的是 B 版本行为完全不一致。排查顺序建议是先看 Console 里有没有程序集加载警告再确认整个工程里只有一份驱动最后看 Player Settings 的 API 级别这三项占掉第一步翻车的八成原因。2.2 最小可用连接串与连通性验证脚本先证明链路是通的不要一上来就写完整业务逻辑先写一个几十行的连通性验证脚本把驱动能加载、TCP 能通、账号能认证、字符集能协商这四件事一次验证完。下面这段是我常用最小版本放在 Editor 菜单里也能跑using UnityEngine; using MySql.Data.MySqlClient; public static class MySqlConnector { public static string BuildConnectionString(string host, int port, string db, string user, string pwd) { return string.Format( Server{0};Port{1};Database{2};User ID{3};Password{4}; Character Setutf8mb4;Poolingtrue;Connection Timeout5;SslModeNone;, host, port, db, user, pwd); } public static bool TryOpen(string connStr, out string error) { try { using (var conn new MySqlConnection(connStr)) { conn.Open(); error null; return true; } } catch (System.Exception e) { error e.Message; return false; } } }这段代码里值得说明的参数按重要程度排Server和Port不用多说注意内网 MySQL 端口默认 3306Connection Timeout5是我强烈建议加的默认值往往太长一旦 IP 不可达UI 上会干等几十秒SslModeNone只适合内网调试环境如果数据库在公网或者公司安全策略要求加密传输这里要改成Required并配置证书Character Setutf8mb4直接决定了后面中文会不会乱码。using包住连接对象保证Open之后即使失败也会释放底层 Socket。写完脚本后在场景里放一个空物体挂测试代码或者直接在[MenuItem]里调用TryOpen把连接串打出来跑一次。这一步过了说明环境和驱动没问题接下来才能放心做查询和 UI。注意驱动命名空间是MySql.Data.MySqlClient如果用的是 MySqlConnector命名空间同样是它但程序集名不同别混用。2.3 连接池与字符集两个不显眼但决定成败的参数很多新人在连接串里不写Pooling这是隐患。驱动默认是开连接池的但开了池子不代表不会炸——如果你每次查询都new MySqlConnection却忘记Close或Dispose池里的连接会被占满后续请求全部排队等超时表现就是查询越跑越慢最后 Timeout expired。反过来频繁开关连接虽然浪费一点握手时间但在 Unity 这种以 UI 为主的环境里简单可靠比极致性能更重要。我个人给内部工具的规范是连接串统一Poolingtrue;Max Pool Size20;Connection Timeout5代码里强制using宁可多几次握手也不让连接泄漏。字符集这一项特别容易被忽略。连接串里写Character Setutf8mb4只是链路的一半另一半在数据库端表结构、字段 collation 也要支持 utf8mb4。两边的字符集不一致时常见结果不是报错而是中文写入后读出来变问号。MySQL 5.7 之前默认 latin1 的情况很多见新建库的时候要注意默认字符集MySQL 8.0 默认已经是 utf8mb4反而问题少。另外一个细节连接串参数名是Character Set有些驱动也接受Charset别名但为了兼容性我统一写全称。最后提一个连接串里容易被忽略的字段Database可以先不填连上去后执行USE dbname;也是可以的这在做列出所有库的管理工具时反而更灵活。不过 Simple TableUI 的场景通常是固定连某个业务库直接在连接串里写Database最省事还能少一次命令往返。3. 从查询结果到 TableUI 数据模型把 DataTable 拆成能渲染的结构3.1 把查询封装成 DataTable读库代码的最小可用版本查询封装的目标很朴素输入一条 SQL输出一个独立的DataTable调用方不用关心连接怎么开、命令怎么执行。注意DataTable在Fill之后已经和数据源断开连接关闭后数据仍然可用这是它能安全跨线程传递的前提。using System.Data; using MySql.Data.MySqlClient; public static class MySqlQuery { public static DataTable Query(string connStr, string sql, MySqlParameter[] parameters null) { using (var conn new MySqlConnection(connStr)) using (var cmd new MySqlCommand(sql, conn)) { cmd.CommandTimeout 10; if (parameters ! null) { cmd.Parameters.AddRange(parameters); } conn.Open(); using (var adapter new MySqlDataAdapter(cmd)) { var dt new DataTable(); adapter.Fill(dt); return dt; } } } }这里的逻辑要点是双层using外层管连接和命令内层管适配器任何一层抛异常都能保证连接被归还给池。CommandTimeout10是对应连接串里Connection Timeout5的前者是单条命令执行时限后者是建立连接时限两个都要设只设一个救不了另一个。MySqlParameter参数数组是为了防 SQL 注入凡是把外部字符串拼进 SQL 的地方都应该走参数化比如WHERE name LIKE kw。内部工具也建议养成这个习惯因为迟早会把工具开放给非技术同事用。一个容易被忽略的细节adapter.Fill(dt)返回的是受影响行数但不代表结果集行数不要拿它判断有没有数据。判断空表要用dt.Rows.Count。还有Fill会自动把表结构带出来包括列名、列类型、是否允许空值这些元信息在第四章生成表头时会直接用。3.2 字段类型映射从 MySQL 类型到 C# 类型的对照表DataTable里的列类型不会原样保留 MySQL 的类型而是被映射成了 .NET 类型。不理解这层映射表格 UI 就会在显示层出现莫名其妙的玄学数字变布尔、时间带毫秒、金额丢精度。下面是我实际踩过的高频映射关系MySQL 类型.NET 类型DataTable 中说明TINYINT(1)bool最常见翻车点1 和 0 变成 true/falseTINYINT / SMALLINTsbyte / short注意范围TINYINT(2) 不会被映射成 boolINT / BIGINTint / long常规无歧义DECIMAL / NUMERICdecimal必须用 decimal 运算转 double 会丢精度DATETIME / TIMESTAMPDateTime读进来是本地时间还是 UTC 取决于驱动与服务器时区DATEDateTime时间部分为 00:00:00CHAR / VARCHAR / TEXTstring常见无歧义BLOB / BINARYbyte[]表格里不能直接显示要处理成摘要JSONstringMySQL 8 的 JSON 在驱动层通常按字符串返回这张表不用背但有两类值得形成条件反射。第一类是TINYINT(1)它在 MySQL 里是布尔用整数表示的历史遗留驱动默认直接转成bool如果你的业务真的用 0/1 存状态位倒是省事如果存的是枚举值 0/1/2那就会被截断或者报转换错误。第二类是DateTime驱动读出来会根据服务器的time_zone和连接串里的Connection Timezone做转换如果两边时区不一致表格里看到的时间会和数据库里差几个小时。还有一个更隐蔽的问题DataTable的列允许DBNull.Value它不是null。如果用row[col]直接拿值然后ToString()DBNull会变成空字符串而不是我们想要的占位符 - 。所以所有单元格格式化函数的第一行都必须是空值判断这在 4.3 节会给出统一写法。3.3 异步查询与主线程别让 UI 卡死在 Open 和 Fill 上Unity 的主线程承担渲染和 UI 事件如果在主线程里直接执行conn.Open()和adapter.Fill()网络延迟加上大数据量序列化轻则编辑器卡几秒重则移动端直接 ANR应用无响应弹窗。编辑器里卡住还可以忍打包到真机上就是事故。所以查询必须挪出主线程。在 Unity 里我常用的模式是协程加Task.Run不用引额外的线程调度库using System.Collections; using System.Data; public static IEnumerator QueryAsyncRoutine(string connStr, string sql, System.ActionDataTable, string onDone) { DataTable result null; string error null; yield return System.Threading.Tasks.Task.Run(() { try { result MySqlQuery.Query(connStr, sql); } catch (System.Exception e) { error e.Message; } }); onDone?.Invoke(result, error); }这里的关键机制是Task.Run把查询丢到线程池线程执行yield return挂起协程但不会阻塞主线程任务完成后协程从暂停处继续执行而 Unity 的协程恢复是发生在主线程的。所以onDone回调里的代码可以放心操作 UI不需要再额外切线程。需要注意在任务内部不要碰任何UnityEngine对象DataTable是纯 .NET 对象所以没问题。调用方的写法是StartCoroutine(QueryAsyncRoutine(connStr, sql, (dt, err) { ... }))。回调里要先判err再做 UI 绑定。如果要在协程间传数据推荐把DataTable暂存到一个字段等下一帧再用避免回调闭包里做太重的工作。另外Task.Run在较老的 Unity 版本上需要 API 兼容级别不低于.NET 4.x这正好呼应第二章的环境检查。4. Simple TableUI 落地动态生成表头、表体与滚动复用4.1 表头与列宽从 DataTable 的元信息动态生成拿到DataTable后第一步不是循环行而是先看Columns因为表头完全由它决定。列名、列类型、是否可空都是现成的元信息动态生成表头可以做到换一张表UI 不用改代码。using UnityEngine; using UnityEngine.UI; public class TableView : MonoBehaviour { public RectTransform headerRoot; public GameObject cellPrefab; public void BuildHeader(DataTable dt) { ClearChildren(headerRoot); for (int i 0; i dt.Columns.Count; i) { var col dt.Columns[i]; var cell Instantiate(cellPrefab, headerRoot).GetComponentText(); cell.text col.ColumnName; cell.rectTransform.sizeDelta new Vector2( EstimateColumnWidth(dt, i), headerRoot.rect.height); } } private float EstimateColumnWidth(DataTable dt, int colIndex) { float maxLen dt.Columns[colIndex].ColumnName.Length; int sample Mathf.Min(50, dt.Rows.Count); for (int r 0; r sample; r) { object v dt.Rows[r][colIndex]; if (v ! null v ! System.DBNull.Value) { maxLen Mathf.Max(maxLen, v.ToString().Length); } } return Mathf.Clamp(maxLen * 14f 24f, 80f, 320f); } }列宽估算的逻辑是取列名字长和前 50 行数据的最大字符串长度乘以一个经验字号系数这里是 14 像素/字符再加 24 像素留白最后限制在 80 到 320 之间。这个系数在字号 14~16 的 UI 下够用如果你把字体改大系数要跟着调。只采样前 50 行是为了避免大数据量下取maxLen变成全表扫描——显示层不应该承担数据层的复杂度。这里有个表格 UI 的通用原则表头和数据行的列宽必须保持一致否则纵向对齐会乱。最简单的实现是让表头和数据区共用同一套列宽数组我在TableView里存了一个float[] _columnWidths表头生成时写入数据行渲染时读取这样两边永远不会不一致。4.2 表体行渲染ScrollRect 加对象池不要 Instantiate 一万行一万行数据如果全量实例化场景里多出上万个 GameObject编辑器都会喘。所以表体必须做两件事外层用ScrollRect限制可视区域内层用对象池只渲染可视行加上下缓冲。这是 Simple TableUI 里性能最关键的 20 行代码。using System.Collections.Generic; using UnityEngine; public class RowPool { private readonly StackRectTransform _pool new StackRectTransform(); private readonly Transform _parent; private readonly GameObject _rowPrefab; public RowPool(GameObject rowPrefab, Transform parent) { _rowPrefab rowPrefab; _parent parent; } public RectTransform Get() { if (_pool.Count 0) { var row _pool.Pop(); row.gameObject.SetActive(true); return row; } return Object.Instantiate(_rowPrefab, _parent).GetComponentRectTransform(); } public void Return(RectTransform row) { row.gameObject.SetActive(false); _pool.Push(row); } }对象池的逻辑很简单取行时优先复用池里的没有才Instantiate还行时SetActive(false)而不是Destroy。但真正的技巧在滚动事件里不要在ScrollRect.onValueChanged里对每帧都做全量重建而是记录当前滚动位置对应的起始行索引只有索引变化时才重新绑定可视区行。public void OnScroll(Vector2 pos) { float rowHeight _rowHeight; int totalRows _data.Rows.Count; int viewportRows Mathf.CeilToInt(_viewportHeight / rowHeight) 2; int startRow Mathf.FloorToInt(pos.y * totalRows - viewportRows * 0.5f); startRow Mathf.Max(0, Mathf.Min(startRow, totalRows - viewportRows)); if (startRow _lastStartRow) return; _lastStartRow startRow; for (int i _activeRows.Count - 1; i 0; i--) { int rowIndex _activeRows[i]; if (rowIndex startRow || rowIndex startRow viewportRows) { _pool.Return(_activeRowObjs[i]); _activeRows.RemoveAt(i); _activeRowObjs.RemoveAt(i); } } for (int r startRow; r startRow viewportRows; r) { // 重新定位 row 的 anchoredPosition } }这段是典型的数据绑定可视区行数由视口高度除以行高得出加 2 行作为缓冲防止快速滚动时闪空。滚动超过半屏才重建否则return避免每帧做无意义的对象搬运。如果数据量真的到了几十万行对象池依然扛得住瓶颈会转移到每行的单元格文本更新上这时候再考虑单元格级复用行级复用已经不够了。4.3 单元格格式化时间、小数、空值与布尔值的显示策略数据是数据显示是显示两者不能混。数据库里的0.666666直接ToString()会变成一长串小数true会显示成 True 而不是是DateTime会带毫秒和时区后缀。所以每个单元格在写入 Text 之前都要过一道格式化函数。public static string FormatCell(DataRow row, int colIndex) { object v row[colIndex]; if (v null || v System.DBNull.Value) return -; var type row.Table.Columns[colIndex].DataType; if (type typeof(bool)) return (bool)v ? 是 : 否; if (type typeof(decimal)) return ((decimal)v).ToString(0.##); if (type typeof(System.DateTime)) return ((System.DateTime)v).ToString(yyyy-MM-dd HH:mm:ss); if (type typeof(byte[])) return [BLOB ((byte[])v).Length bytes]; return v.ToString(); }这段代码的顺序是有讲究的空值判断必须放在最前面因为DBNull.Value做GetType()会拿到DBNull而不是列类型bool判断放在数值判断前面因为bool不是decimal的子类但如果顺序写反先匹配到IConvertible之类的通用分支就会走错byte[]判断放在最后兜底因为数组类型转换不成字符串。数值格式化用的是0.##意思是最多两位小数、不强制补零金额类字段如果业务要求两位小数改成F2即可。这里要提醒一件事格式化函数返回的是字符串但如果某些列后续要做排序、筛选不能拿格式化后的字符串排序否则 10 会排在 9 前面。正确做法是排序基于原始DataTable只在显示那一层调用FormatCell这也是第六章排序技巧的前提。5. Unity 连 MySQL 常见问题与避坑排查现象、原因、解决5.1 现象运行时报 TypeInitializationException或者找不到 MySql.Data 程序集现象代码编译通过但一执行到new MySqlConnection就抛System.TypeInitializationException或者直接FileNotFoundExceptionConsole 里看不到具体 inner exception。原因九成是驱动 DLL 与项目 API 兼容级别不匹配。老驱动引用了一些 Unity 的托管环境里不存在的程序集初始化静态字段时就炸了还有小概率是工程里存在多份驱动 DLL版本互相覆盖。解决先确认 Player Settings 的 API Compatibility Level统一到.NET Standard 2.1并换用 MySqlConnector再全局搜一遍工程确认只有一份驱动最后看异常堆栈里的 inner exception它通常会告诉你缺的具体是哪个程序集。如果项目锁死了.NET Framework 4.x就反过来找针对该目标框架编译的驱动版本。5.2 现象TINYINT(1) 字段显示成是/否数字 0/1 变成布尔现象某字段在数据库里是tinyint(1)存的是 0、1表格里却渲染出是/否两个汉字或者排序时全乱套。原因MySQL 的TINYINT(1)在驱动层被默认映射为bool这是历史兼容设计不是 bug。如果业务语义确实是布尔问题不大如果存的是枚举值就是类型误判。解决改查询 SQL用CAST(col AS SIGNED)把字段在 SQL 层转回整数或者在DataTable拿到后检测列类型为bool且业务确实要显示 0/1就复制一列手动转成int。我倾向于前者因为改动面积小SQL 一眼能看懂而且不影响其他消费方。5.3 现象中文全部变成问号或乱码现象表头、数据里的中文在 UI 上显示成???或æ··ä¹±之类乱码英文数字正常。原因字符集链路断了某一环。连接串没写Character Setutf8mb4、数据库表本身是 latin1、或者驱动版本太老不支持 utf8mb4三种情况的表现不完全一样连接串问题通常是中文变?表字段问题通常是插入时就已损坏。解决诊断顺序是先查表SHOW CREATE TABLE tb\\G看字段 collation再查连接串是否带Character Setutf8mb4最后查 MySQL 版本和驱动版本。最省心的做法是统一到 utf8mb4连接串、数据库、表、字段四级全部对齐缺一级都可能在某个边缘路径上翻车。5.4 现象编辑器能连打包到 Android/iOS 后连不上或白屏现象Editor 里查询正常打成安卓包后点击查询毫无反应或者直接白屏日志里有网络异常或SslMode报错。原因三个叠加因素。第一是 IL2CPP 的代码剪裁把驱动里通过反射加载的类型裁掉了第二是localhost在移动端指向手机自身而不是电脑第三是 Android 上缺互联网权限系统静默拒绝网络请求。解决打包前在 Player Settings 的 IL2CPP 选项里把驱动程序集加入Preserve列表或用[Preserve]特性标记关键类型连接串里的地址改成电脑的局域网 IP不要用localhostAndroid Manifest 里加INTERNET权限。这三件事只要漏一件真机表现就是编辑器一切正常打包即废。5.5 现象查询偶尔卡死几秒后报 Timeout expired现象查询第一次很快多跑几次后越来越慢最后抛超时异常或者偶发卡死恢复后连接池全空。原因连接泄漏占大头。某个分支里conn.Open()之后没走using异常一抛连接没有归还给池池被耗尽后后续请求全部排队。第二个常见原因是长时间未用的连接被 MySQL 服务端断开但池不知道取出来直接操作就报错。解决全工程搜索new MySqlConnection确保每一个都包在using里连接串加Connection Timeout5让失败快速暴露而不是干等再设置Connection Lifetime300让池定期清理超龄连接。如果是长事务或者 sleep 时间超过服务端wait_timeout考虑查空表时顺手Ping一下连接。6. 让 Simple TableUI 更好用的三个进阶习惯6.1 分页查询别用 LIMIT 10 就完事Simple TableUI 做出来后第一个功能诉求几乎都是数据太多。我的习惯是连接串之外的 SQL 层直接做分页LIMIT offset,count加上一条SELECT COUNT(*)拿总数UI 底部放页码。注意OFFSET大的时候要用延迟关联优化先LIMIT拿主键再反查明细否则二十万行翻到后面照样慢。6.2 点击表头排序永远基于原始值排序给表头加一个点击事件点击时切换排序方向。关键原则是排序必须作用在DataTable的原始列值上而不是格式化后的字符串。DataTable自带DefaultView.Sort colName ASC直接改视图排序再重新绑定可视行是最便宜的做法一二十行代码就能支持多列和升降序。6.3 把格式化器做成可替换的委托FormatCell这种散落的静态函数有个缺点换个业务表就要改函数体。第三步我会把它改成FuncDataRow, int, string委托由表格外部注入。这样同一套TableView组件一套通用格式化器加一两个业务自定义列格式化器就能覆盖所有内部工具的表单场景。我吃过亏的地方是刚开始把格式化逻辑写死在 UI 类里第二张表需求一来就要复制改类改了三张表之后才彻底拆开。这套方案做下来我最深的教训是连接串、驱动选型、类型映射这三件事必须在一开始定死后面返工的代价远大于写代码本身。每一次踩坑其实都在提醒我数据链路最怕的不是 SQL 写错而是环境不一致和资源不放回。希望这个从连接串到滚动复用、再到排错清单的完整流程能帮到你少走几趟我走过的弯路。本文还有配套的精品资源点击获取