告别Excel.dll！在Unity 2018+中用ExcelDataReader轻松搞定.xlsx表格读取（保姆级避坑指南）
Unity 2018+实战指南：用ExcelDataReader零障碍解析xlsx表格
在游戏开发中，数据驱动设计已经成为主流趋势。无论是配置关卡参数、管理多语言文本，还是存储角色属性，Excel表格因其直观的界面和强大的功能，成为开发者最青睐的数据存储格式之一。然而，Unity与Excel的集成却一直是个令人头疼的问题——传统基于Excel.dll的方案不仅步骤繁琐，而且对新版xlsx格式的支持极不稳定，经常出现莫名其妙的报错。本文将带你彻底摆脱这些困扰，通过ExcelDataReader这套轻量级解决方案，实现Unity与Excel的无缝对接。
1. 为什么选择ExcelDataReader？
在深入技术细节之前，有必要了解为什么ExcelDataReader会成为Unity社区处理Excel文件的首选方案。与传统的Excel.dll方案相比，ExcelDataReader具有几个不可替代的优势：
- 无Office依赖：不需要在目标机器安装Microsoft Office，解决了部署难题
- 跨平台支持：完美兼容Windows、Mac和Linux三大平台
- 轻量高效：核心DLL仅300KB左右，不会增加项目体积负担
- 专注读取：专为数据读取优化，比全功能Excel库更高效
- MIT许可证：完全免费且可商用，无法律风险
特别值得注意的是，ExcelDataReader对xlsx这种基于OpenXML的新格式有着原生支持，完全避免了传统方案中常见的"文件格式不兼容"错误。根据社区反馈，即使是超过10MB的大型Excel文件，也能在Unity中流畅读取。
2. 环境准备与DLL获取
2.1 创建.NET控制台项目
虽然最终目标是Unity项目，但我们首先需要通过一个简单的.NET控制台应用来获取正确的DLL文件。这个中间步骤至关重要，它能帮助我们规避Unity编辑器环境下NuGet包管理的各种限制。
# 推荐使用Visual Studio 2019或更高版本 # 新建项目 → 控制台应用(.NET Framework) → 选择.NET 4.x版本注意：这里选择的.NET Framework版本应该与你的Unity项目设置保持一致。Unity 2018默认使用.NET 4.x等效运行时，因此建议选择.NET Framework 4.7.2以获得最佳兼容性。
2.2 通过NuGet安装ExcelDataReader
在Visual Studio中安装NuGet包非常简单：
- 右键点击项目 → 选择"管理NuGet程序包"
- 在浏览选项卡搜索"ExcelDataReader"
- 安装以下两个核心包：
- ExcelDataReader (v3.6.0+)
- ExcelDataReader.DataSet (v3.6.0+)
安装完成后，你可以在解决方案资源管理器的"引用"部分看到新增的依赖项。但我们需要的是实际的DLL文件，它们通常位于项目的packages文件夹内。
2.3 定位并选择合适的DLL版本
在解决方案资源管理器中展开"引用"，右键点击ExcelDataReader → 属性，可以看到"路径"属性指向了具体的DLL文件位置。导航到该目录，你会发现类似如下的文件夹结构：
lib/ ├── net20/ │ ├── ExcelDataReader.dll │ └── ExcelDataReader.DataSet.dll ├── net45/ │ ├── ExcelDataReader.dll │ └── ExcelDataReader.DataSet.dll └── netstandard2.0/ ├── ExcelDataReader.dll └── ExcelDataReader.DataSet.dll对于Unity 2018+项目，建议选择net45版本，因为它提供了最佳的兼容性和性能平衡。将这两个DLL文件复制到临时位置备用。
3. Unity项目集成实战
3.1 准备Unity项目结构
回到Unity编辑器，按照以下步骤配置项目：
- 在Assets目录下创建
Plugins文件夹（如果不存在） - 将之前获取的两个DLL文件复制到
Plugins文件夹 - 对于Unity 2017及更早版本，还需要手动添加
System.Data.dll（位于.NET Framework安装目录）
提示：在Mac系统上，可能需要右键点击DLL文件 → 选择"Show in Finder"来验证文件是否被正确导入。
3.2 处理可能的兼容性问题
不同Unity版本对.NET支持有所差异，以下是常见问题及解决方案：
| Unity版本 | 推荐DLL版本 | 额外依赖 | 已知问题 |
|---|---|---|---|
| 2017.x | net20 | System.Data.dll | 可能需手动添加Ionic.Zip.dll |
| 2018.x | net45 | 无 | 无 |
| 2019.x+ | netstandard2.0 | 无 | IL2CPP需额外配置 |
如果遇到"BadImageFormatException"错误，通常是因为DLL版本与Unity的.NET配置不匹配。这时可以尝试：
- 检查Player Settings中的API Compatibility Level
- 尝试不同版本的DLL文件
- 确保所有DLL都来自同一发布版本
3.3 编写核心读取代码
创建一个新的C#脚本（如ExcelLoader.cs），以下是经过优化的读取示例：
using ExcelDataReader; using System.IO; using UnityEngine; public class ExcelLoader : MonoBehaviour { public string excelPath = "Data/test.xlsx"; void Start() { // 构建完整路径（兼容Editor和运行时） string fullPath = Path.Combine(Application.streamingAssetsPath, excelPath); // 确保文件存在 if (!File.Exists(fullPath)) { Debug.LogError($"Excel文件不存在: {fullPath}"); return; } // 配置ExcelDataReader的自动解析 System.Text.Encoding.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance); using (var stream = File.Open(fullPath, FileMode.Open, FileAccess.Read)) using (var reader = ExcelReaderFactory.CreateReader(stream)) { // 读取整个工作表到DataSet var dataSet = reader.AsDataSet(new ExcelDataSetConfiguration() { ConfigureDataTable = (_) => new ExcelDataTableConfiguration() { UseHeaderRow = true // 第一行作为列名 } }); // 遍历第一个工作表 var table = dataSet.Tables[0]; for (int i = 0; i < table.Rows.Count; i++) { var row = table.Rows[i]; for (int j = 0; j < table.Columns.Count; j++) { Debug.Log($"行{i},列{j}: {row[j]}"); } } } } }这段代码做了几项重要改进：
- 使用
StreamingAssets路径，确保打包后仍能访问文件 - 添加了完善的错误检查
- 配置了表头解析，使数据更结构化
- 使用
using语句确保资源正确释放
4. 高级应用与性能优化
4.1 处理大型Excel文件
当处理包含数万行数据的Excel文件时，内存使用和性能成为关键考量。以下是几个优化技巧：
- 流式读取：不要一次性加载整个文件，而是逐行处理
while (reader.Read()) // 逐行读取 { // 处理当前行数据 var value = reader.GetString(0); // 获取第一列值 }- 选择性加载：只读取需要的列
var dataSet = reader.AsDataSet(new ExcelDataSetConfiguration() { FilterColumn = (reader, index) => index < 5 // 只读取前5列 });- 后台线程：将读取操作放到非主线程执行
async void LoadExcelAsync() { await Task.Run(() => { // 在这里执行读取操作 }); }4.2 数据转换与验证
直接从Excel读取的数据通常需要进一步处理才能用于游戏逻辑。建议创建一个专门的数据处理器：
public class ItemData { public int ID; public string Name; public float Price; public static ItemData FromDataRow(DataRow row) { return new ItemData() { ID = Convert.ToInt32(row["ID"]), Name = row["名称"].ToString(), Price = float.Parse(row["价格"].ToString()) }; } } // 使用示例 var item = ItemData.FromDataRow(table.Rows[0]);4.3 自动化工作流
为了提升开发效率，可以考虑实现以下自动化流程：
- 编辑器扩展：创建自定义Inspector，一键导入Excel数据
[CustomEditor(typeof(ExcelLoader))] public class ExcelLoaderEditor : Editor { public override void OnInspectorGUI() { base.OnInspectorGUI(); if (GUILayout.Button("导入Excel")) { (target as ExcelLoader).ReloadData(); } } }自动生成脚本：根据Excel表结构自动创建对应的C#数据类
版本控制友好：将Excel转换为JSON或CSV等文本格式后再提交
5. 常见问题解决方案
在实际项目中，你可能会遇到以下典型问题：
问题1：运行时抛出"System.Text.Encoding not found"异常
解决：在代码开头添加：
System.Text.Encoding.RegisterProvider( System.Text.CodePagesEncodingProvider.Instance);问题2：读取的日期格式显示为数字
解决：使用DateTime.FromOADate转换Excel日期值：
var date = DateTime.FromOADate(double.Parse(cellValue.ToString()));问题3：IL2CPP构建失败
解决：在Assets/link.xml中添加：
<linker> <assembly fullname="ExcelDataReader" preserve="all"/> <assembly fullname="System.Data" preserve="all"/> </linker>问题4：Mac上文件路径问题
解决：使用Path.Combine并确保路径使用正斜杠：
string path = Path.Combine(Application.streamingAssetsPath, "Data/test.xlsx");对于更复杂的场景，如需要写入Excel或处理特殊格式，可以考虑结合EPPlus等库使用。但在大多数游戏开发场景中，ExcelDataReader提供的读取功能已经足够强大。