前言

MySQL装好了、表也建好了，现在轮到Unity这边了。本篇解决三个问题：选哪个驱动、怎么导入、如何跑通第一个查询。这是整个系列中最容易踩坑的一步，因为Unity的Mono/IL2CPP环境和标准.NET有微妙差异。

一、三大驱动选型对比

维度 MySql.Data (官方) MySqlConnector (开源) FreeSql (ORM)
NuGet包 MySql.Data MySqlConnector FreeSql + Provider
Unity兼容 ⚠️ 需手动处理依赖 ✅ 原生支持netstandard2.0 ✅ 内置适配
异步支持 有但历史包袱重 ✅ 原生async/await ✅ 完整异步
API风格 ADO.NET传统 ADO.NET兼容+异步增强 Lambda表达式/实体映射
CRUD代码量 高(SQL全手写) 中(SQL仍手写) 低(ORM自动映射)
IL2CPP兼容 ⚠️ 偶发反射异常 ✅ 稳定 ✅ 稳定
社区活跃度 官方维护但更新慢 活跃开源社区 国内活跃(GitHub 14k+)
推荐场景 遗留项目维护 轻量直连/学习 新项目首选

💡 本系列选择：教学演示用 MySqlConnector（理解底层原理），实战项目推荐 FreeSql（开发效率高）。

二、导入MySqlConnector到Unity

2.1 通过NuGet For Unity（推荐）

  1. 安装 NuGetForUnity
  2. Unity菜单 → NuGet → Manage NuGet Packages
  3. 搜索 MySqlConnector，安装最新稳定版
  4. 自动下载到 Packages/ 目录，无需手动管理DLL

2.2 手动导入DLL（详细步骤）

Step 1：下载正确的DLL

从 NuGet官网 下载最新稳定版的 .nupkg 文件（本质是zip），解压后进入 lib/netstandard2.0/ 目录，取出以下文件：

1
MySqlConnector.dll          ← 核心驱动（必选）

⚠️ 必须选 netstandard2.0 版本。net6.0/net8.0版本在Unity中无法使用。如果项目用的是Unity 2019.x，可能需要netstandard2.0或net461版本。

Step 2：创建Plugins目录并放入DLL

1
2
3
4
5
# 在Unity项目中创建Plugins文件夹（如果不存在）
mkdir -p /path/to/YourProject/Assets/Plugins

# 将DLL复制到Plugins目录
cp MySqlConnector.dll /path/to/YourProject/Assets/Plugins/

或者直接在Unity Editor中操作：

  1. 在Project窗口右键 Assets → Create → Folder，命名为 Plugins
  2. 将下载的 MySqlConnector.dll 拖入 Assets/Plugins/ 目录

Step 3：检查DLL导入设置

在Unity Inspector中选中的 MySqlConnector.dll，确认以下设置：

设置项 推荐值 说明
Validate References ✅ 勾选 自动检查依赖完整性
Auto Referenced ✅ 勾选 自动添加到编译引用
Platform settings All platforms 确保所有目标平台都勾选

💡 如果同时使用了NuGetForUnity，它会自动处理这些设置。手动导入时需要自己确认。

Step 4：处理依赖问题

MySqlConnector可能依赖 System.Memory、System.Buffers 等库。如果编译报错提示缺少类型：

1
2
3
4
5
6
# 同样从NuGet下载对应包的netstandard2.0版本DLL
# 一并放入 Assets/Plugins/
# 常见需要补充的依赖：
#   System.Memory.dll
#   System.Buffers.dll  
#   System.Runtime.CompilerServices.Unsafe.dll

⚠️ Unity 2021.2+ 已内置大部分System命名空间类型，通常不需要额外添加。只有旧版Unity才需要手动补依赖。

2.3 验证导入成功

1
2
3
4
5
6
7
8
9
10
using MySqlConnector;
using UnityEngine;

public class DbTest : MonoBehaviour
{
    void Start()
    {
        Debug.Log($"MySqlConnector version: {typeof(MySqlConnection).Assembly.GetName().Version}");
    }
}

控制台输出版本号即表示导入成功。

三、连接字符串配置

3.1 使用ScriptableObject外置配置（安全！）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[CreateAssetMenu(fileName = "DatabaseConfig", menuName = "Configs/Database Config")]
public class DatabaseConfig : ScriptableObject
{
    public string host = "127.0.0.1";
    public int port = 3306;
    public string database = "game_db";
    public string user = "game_app";
    [HideInInspector] public string password = "";

    public string ConnectionString =>
        $"server={host};port={port};database={database};" +
        $"user={user};password={password};" +
        "charset=utf8mb4;connectiontimeout=5;pooling=true;maxpoolsize=20;";
}

⚠️ 密码不要提交到Git！ 使用 .gitignore 排除或环境变量注入。

3.2 连接字符串关键参数

参数 推荐值 说明
charset utf8mb4 支持emoji和中文
connectiontimeout 5 连接超时秒数，避免卡死
pooling true 启用连接池，复用TCP连接
maxpoolsize 20 最大连接数，根据并发调整
AllowPublicKeyRetrieval true MySQL 8.0认证插件需要
SslMode Preferred 生产环境改为Required

四、跑通第一个查询

4.1 最小可运行示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
using MySqlConnector;
using UnityEngine;

public class FirstQuery : MonoBehaviour
{
    [SerializeField] private DatabaseConfig _dbConfig;

    async void Start()
    {
        try
        {
            using var conn = new MySqlConnection(_dbConfig.ConnectionString);
            await conn.OpenAsync();
            Debug.Log("✅ 数据库连接成功！");

            using var cmd = conn.CreateCommand();
            cmd.CommandText = "SELECT COUNT(*) FROM players";
            var count = await cmd.ExecuteScalarAsync();
            Debug.Log($"📊 玩家总数: {count}");

            cmd.CommandText = "SELECT id, nickname, level, gold FROM players ORDER BY level DESC LIMIT 5";
            using var reader = await cmd.ExecuteReaderAsync();
            while (await reader.ReadAsync())
            {
                Debug.Log($"  [{reader.GetInt64("id")}] {reader.GetString("nickname")} " +
                          $"Lv.{reader.GetInt32("level")} Gold:{reader.GetInt64("gold")}");
            }
        }
        catch (MySqlException ex)
        {
            Debug.LogError($"❌ 数据库错误 [{ex.Number}]: {ex.Message}");
        }
    }
}

4.2 运行结果预期

1
2
3
4
5
✅ 数据库连接成功！
📊 玩家总数: 3
  [3] 暗影刺客 Lv.32 Gold:230000
  [1] 剑圣无双 Lv.25 Gold:158000
  [2] 魔法少女 Lv.18 Gold:72000

五、常见报错速查

错误信息 原因 解决方案
Unable to connect to any specified MySQL hosts IP/端口错误或防火墙拦截 检查MySQL服务状态、telnet测试端口
Access denied for user 账号密码错误或权限不足 重新GRANT授权
Authentication plugin caching_sha2_password cannot be loaded MySQL 8.0认证插件不兼容 连接串加AllowPublicKeyRetrieval=true
TypeInitializationException: MySqlConnector DLL版本不对或缺少依赖 确认使用netstandard2.0版本
Connection must be valid and open 连接已关闭或未打开 确保OpenAsync后再执行命令
中文乱码/问号 字符集不匹配 连接串加charset=utf8mb4
IL2CPP打包后崩溃 AOT裁剪了反射类型 添加link.xml保留相关类型 
1
2
3
4
5
6
<linker>
    <assembly fullname="MySqlConnector">
        <type fullname="MySqlConnector.*" preserve="all"/>
    </assembly>
    <assembly fullname="System.Transactions"/>
</linker>

六、连接池注意事项

1
2
3
4
5
6
7
// ✅ 正确：using自动归还连接到池中
using var conn = new MySqlConnection(config.ConnectionString);
await conn.OpenAsync();
// 操作完成后自动Close并归还

// ❌ 错误：长期持有连接不释放
private MySqlConnection _conn; // 永远不要这样做！

💡 核心认知：new MySqlConnection() 不等于新建TCP连接。连接池开启时，它只是从池中借一个已有连接，用完归还。放心用using，不要自己缓存连接对象。

总结

本篇完成了Unity侧的全部准备工作：驱动选型→导入→配置外置→第一个查询→报错排查。你现在应该能在Unity Editor中成功查到MySQL数据了。

下一篇我们系统实现完整的增删改查操作，并封装一个可复用的DAO层。

系列导航
← 第2篇：MySQL安装与表结构设计
第4篇：增删改查完整实现与DAO封装 →

说些什么吧！

waline