Unity动态读取Excel配置：告别ScriptableObject，根治1252编码问题

1. 项目概述为什么我们要告别ScriptableObject在Unity项目开发中尤其是涉及大量数值平衡、关卡设计、多语言本地化等场景时配置数据的管理一直是个核心痛点。过去几年ScriptableObject几乎是Unity社区处理这类问题的“标准答案”。它确实解决了硬编码的问题让策划或设计师能在不重启游戏的情况下通过Asset文件修改数值。但当你真正深入一个中大型项目尤其是需要与外部团队如策划、运营紧密协作时ScriptableObject的短板就暴露无遗了。首先它的编辑体验对非技术人员极不友好。策划同学需要安装Unity编辑器在Project窗口中找到对应的.asset文件然后在Inspector面板中小心翼翼地填写数据。这个过程容易误操作且缺乏版本管理工具如Git对纯文本变更的友好支持合并冲突时简直就是灾难。其次当配置表结构需要频繁调整或者数据量庞大到成千上万行时在Unity编辑器内操作ScriptableObject会变得异常卡顿甚至引发崩溃。因此回归更通用的数据交换格式——Excel就成了一个自然而然的诉求。Excel几乎是所有策划和运营人员的“母语”他们可以在自己熟悉的工具里自由地进行数据编辑、公式计算、筛选排序。我们的目标就是让Unity运行时能够直接、高效、准确地读取这些Excel文件将其转化为游戏内可用的数据结构从而实现真正的“策划驱动开发”。“动态读取”是这里的关键。我们不希望像一些旧方案那样通过编辑器工具将Excel导出为JSON、CSV或XML再在Unity中解析。那种方式增加了中间步骤破坏了数据的实时性。我们追求的是将Excel文件如.xlsx或.xls放入项目的StreamingAssets或某个可访问的路径游戏运行时可即时读取并加载任何在Excel中的修改都能在下次加载时生效无需重新导出或打包。为了实现这个目标我们选择了ExcelDataReader这个轻量级、高性能的.NET库。它不依赖Office组件纯托管代码实现非常适合在Unity的Mono或IL2CPP环境下运行。然而在集成过程中一个经典的“坑”在等着我们1252编码问题。这通常在你尝试读取某些由旧版Excel或特定区域设置下保存生成的.xls文件时出现错误信息提示“No data is available for encoding 1252”。如果不解决它整个动态读取方案将功亏一篑。本文将带你完整实现这一流程并彻底填平这个编码之坑。2. 核心工具选型为什么是ExcelDataReader面对在Unity中读取Excel的需求社区里有过不少方案。比如使用微软官方的Microsoft.Office.Interop.Excel这需要目标机器安装完整的Office在桌面端尚可但在移动平台或没有Office环境的服务器上完全不可行。再比如将Excel另存为CSV再用StreamReader读取这种方式丢失了多工作表、单元格格式等丰富信息且CSV本身的逗号、换行符转义也是麻烦事。ExcelDataReader库脱颖而出主要基于以下几点考量纯.NET实现零外部依赖它的核心是一个托管程序集不调用任何COM组件或本地Office库。这意味着它可以在任何.NET Standard 2.0兼容的环境下运行包括Unity 2018.3之后的版本。我们只需将它的DLL放入项目的Plugins文件夹或者通过UPM或NuGet安装即可使用。高性能与低内存占用库采用流式读取Streaming方式并非一次性将整个Excel文件加载到内存中。这对于读取几十上百MB的大型配置表至关重要能有效避免Unity移动端应用的内存峰值和卡顿。格式支持全面它支持读取经典的.xlsBIFF格式和现代的.xlsxOpenXML格式涵盖了绝大多数策划会使用的Excel文件类型。API简洁直观核心对象只有IExcelDataReader通过它你可以遍历工作表Worksheets获取行Row和列Cell的数据学习成本极低。当然它不是一个“写”库主要用于读取。但这正好符合我们“动态读取配置”的场景——策划在Excel中编辑游戏运行时读取。写入和复杂格式编辑的工作就交给专业的Excel软件本身。注意Unity 2021.2及以上版本对.NET Standard 2.1和.NET 5/6的支持更为完善但ExcelDataReader的核心版本如v3.6.0基于.NET Standard 2.0具有最好的兼容性。建议在Unity 2020.3 LTS或2019.4 LTS等长期支持版本中使用稳定性最有保障。2.1 环境准备与库的导入首先我们需要获取ExcelDataReader及其依赖项。最可靠的方式是通过NuGet包但对于Unity项目我们通常手动导入DLL。下载必要的DLL你需要下载两个核心DLLExcelDataReader.dllExcelDataReader.DataSet.dll如果你需要将数据直接转换为System.Data.DataSet这个很有用 可以从其GitHub仓库的Release页面下载编译好的版本或者通过NuGet包管理器提取。处理依赖项ExcelDataReader对于.xlsx文件OpenXML格式的读取依赖于System.IO.Packaging。幸运的是现代Unity版本已经包含了这个程序集。对于.xls文件BIFF格式它依赖于ICSharpCode.SharpZipLib来处理压缩。Unity本身也内置了SharpZipLib但版本可能较旧。为了避免冲突最安全的方法是使用ExcelDataReader包中自带的那个。通常下载的包内会包含一个lib文件夹里面有ICSharpCode.SharpZipLib.dll。导入Unity项目在Assets目录下创建Plugins文件夹如果不存在。将下载的ExcelDataReader.dll、ExcelDataReader.DataSet.dll以及ICSharpCode.SharpZipLib.dll如果需要复制到Assets/Plugins下。由于这些是托管DLL需要特别注意平台兼容性设置。在Unity编辑器中选中这些DLL在Inspector面板中确保“Any Platform”被选中。对于“WSAPlayer”Universal Windows Platform通常需要取消勾选除非你明确开发UWP应用因为可能涉及.NET Native编译问题。“Enable .NET 4.x Equivalent”或“Enable .NET Standard 2.0”的兼容性模式需要根据你的Unity版本设置保持一致。完成以上步骤后你可以在C#脚本中通过using ExcelDataReader;来引入命名空间环境就搭建好了。3. 动态读取Excel的完整流程解析让我们抛开理论直接构建一个可复用的Excel读取管理器。这个管理器需要完成以下任务定位文件、创建读取流、配置解码器、读取数据、并转换为易于游戏使用的数据结构例如ListDictionarystring, object或自定义类列表。3.1 构建Excel读取管理器我们将创建一个名为ExcelDataManager的单例类它提供同步和异步的加载方法。using System; using System.Collections.Generic; using System.IO; using System.Text; using ExcelDataReader; using UnityEngine; public class ExcelDataManager : MonoBehaviour { private static ExcelDataManager _instance; public static ExcelDataManager Instance _instance; private void Awake() { if (_instance ! null _instance ! this) { Destroy(gameObject); return; } _instance this; DontDestroyOnLoad(gameObject); // 关键一步注册编码提供程序解决1252编码问题 System.Text.Encoding.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance); } /// summary /// 同步读取Excel文件并返回一个字典列表每行一个字典键为列名 /// /summary /// param namefilePathExcel文件路径相对于StreamingAssets或绝对路径/param /// param namesheetIndex工作表索引默认为0第一个工作表/param /// param namehasHeader第一行是否为列标题Header默认为是/param /// returns/returns public ListDictionarystring, object ReadExcel(string filePath, int sheetIndex 0, bool hasHeader true) { // 结果列表 var result new ListDictionarystring, object(); // 列标题列表 Liststring headers new Liststring(); // 1. 构建完整文件路径 string fullPath Path.Combine(Application.streamingAssetsPath, filePath); // 如果是在Android平台上读取StreamingAssets需要用UnityWebRequest这里为简化先处理本地路径。 // 实际项目中对于Android的StreamingAssets需要先将其复制到可读写路径如PersistentDataPath再读取。 if (!File.Exists(fullPath)) { Debug.LogError($Excel文件不存在于路径: {fullPath}); return result; } // 2. 打开文件流 using (var stream File.Open(fullPath, FileMode.Open, FileAccess.Read)) { // 3. 创建ExcelReader // AutoDetectFormat: 自动检测是xls还是xlsx // FallbackEncoding: 非常重要指定回退编码为UTF-8这是解决乱码问题的第一道防线 using (var reader ExcelReaderFactory.CreateReader(stream, new ExcelReaderConfiguration() { FallbackEncoding Encoding.GetEncoding(utf-8) })) { // 4. 读取指定工作表的数据集 var dataSet reader.AsDataSet(new ExcelDataSetConfiguration() { // 配置如何读取数据 ConfigureDataTable (_) new ExcelDataTableConfiguration() { UseHeaderRow hasHeader, // 使用第一行作为列名 EmptyColumnNamePrefix Column, // 空列名的前缀 FilterRow (rowReader) { // 这里可以过滤行例如跳过空行 // 示例如果第一列为空则跳过该行 // return rowReader.GetValue(0) ! null; return true; // 不过滤 } } }); // 5. 获取指定的工作表 if (dataSet.Tables.Count sheetIndex) { Debug.LogError($工作表索引 {sheetIndex} 超出范围。文件共有 {dataSet.Tables.Count} 个工作表。); return result; } var dataTable dataSet.Tables[sheetIndex]; // 6. 提取列标题 if (hasHeader) { foreach (System.Data.DataColumn column in dataTable.Columns) { headers.Add(column.ColumnName); } } else { // 如果没有标题行则生成默认列名如Col0, Col1... for (int i 0; i dataTable.Columns.Count; i) { headers.Add($Col{i}); } } // 7. 遍历行构建字典 foreach (System.Data.DataRow row in dataTable.Rows) { var rowDict new Dictionarystring, object(); for (int i 0; i headers.Count; i) { // 将数据存入字典键为列标题值为单元格数据 rowDict[headers[i]] row[i]; } result.Add(rowDict); } } } Debug.Log($成功从 {filePath} 读取 {result.Count} 行数据。); return result; } // 异步读取方法示例实际需在协程或异步任务中调用 public IEnumeratorobject ReadExcelAsync(string filePath, ActionListDictionarystring, object onComplete, int sheetIndex 0, bool hasHeader true) { var data new ListDictionarystring, object(); // 在实际实现中这里应该将文件读取和解析放到线程池中避免阻塞主线程 // 由于Unity的API限制复杂的多线程需要小心处理这里简化为在协程中调用同步方法 yield return null; // 模拟一帧延迟 data ReadExcel(filePath, sheetIndex, hasHeader); onComplete?.Invoke(data); } }这个管理器提供了核心的同步读取功能。它通过ExcelReaderFactory.CreateReader创建阅读器并通过AsDataSet方法将整个工作表读入一个熟悉的System.Data.DataTable对象中进而方便地转换为字典列表。这种结构非常灵活适合结构可能变化的配置表。3.2 编码问题深度剖析与1252编码陷阱的根治现在我们来直面最棘手的“1252编码”问题。当你运行上述代码读取某些.xls文件时可能会遇到如下异常System.NotSupportedException: No data is available for encoding 1252. For information on defining...这个错误的根源是什么1252编码即“Windows-1252”或“ANSI”编码是一种单字节字符集常用于早期的西欧语言Windows系统。.xlsBIFF8格式文件内部存储字符串时可能会使用这种编码来标识。.NET Core和.NET 5/6包括Unity基于的这些运行时默认并不包含所有代码页Code Page的编码提供程序以减小发行包体积。因此当ExcelDataReader尝试使用1252编码去解码文件中的字符串时运行时找不到对应的编码器就抛出了异常。解决方案分两步缺一不可安装System.Text.Encoding.CodePages包这是微软官方提供的包它扩展了.NET Core的编码支持包含了1252等大量代码页编码。对于Unity项目我们需要手动引入这个包。如果你使用Unity 2019.4且开启了Package Manager对NuGet的支持通过scopedRegistries配置可以直接在Package Manager中搜索System.Text.Encoding.CodePages并安装。更通用的方法是从NuGet官网下载System.Text.Encoding.CodePages的.nupkg文件解压后找到lib/netstandard2.0/System.Text.Encoding.CodePages.dll将其复制到项目的Assets/Plugins文件夹中。在程序启动时注册编码提供程序仅仅引入DLL还不够必须在任何可能使用到这些编码的操作之前执行一行注册代码。这就是为什么我们在ExcelDataManager的Awake方法中或任何更早的启动脚本中添加了这行关键代码System.Text.Encoding.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance);这行代码告诉.NET运行时“嘿我这里有更多的编码提供程序请把它们加入你的编码池里。” 之后当ExcelDataReader内部调用Encoding.GetEncoding(1252)时运行时就能成功找到并返回该编码而不是抛出异常。实操心得这个注册操作必须且只需执行一次通常放在游戏初始化的入口处如第一个场景的初始化管理器或App入口脚本的Awake或Start中。确保它在任何Excel读取操作之前执行。我曾在一个项目中因为把这行代码放到了某个按需加载的模块里导致首次冷启动读取配置时依然报错排查了很久。额外的编码保险FallbackEncoding在创建ExcelReader时我们传入的ExcelReaderConfiguration中设置了FallbackEncoding Encoding.GetEncoding(utf-8)。这个配置的作用是当阅读器无法自动检测或确定文件使用的编码时将使用UTF-8作为回退方案。UTF-8是现代软件中最通用、最安全的编码这为读取那些编码信息不明确或异常的文件增加了一层保障可以有效避免中文字符等变成乱码。4. 从数据到对象高效反序列化实战读取到Dictionarystring, object列表只是第一步。在游戏代码中我们更希望使用强类型的对象例如一个ItemConfig类或MonsterConfig类这样可以利用IDE的智能提示、类型检查并且性能也更优。我们需要一个将字典数据映射到对象属性的过程。4.1 定义配置数据模型假设我们有一个物品配置表ItemConfig.xlsx包含以下列ID(int),Name(string),Type(enum),Price(int),Description(string)。首先定义对应的C#类和数据枚举public enum ItemType { Consumable, Equipment, Material } [System.Serializable] // 可选方便在Unity编辑器中查看 public class ItemConfig { public int ID; public string Name; public ItemType Type; public int Price; public string Description; // 可以添加一个从字典初始化的构造函数或方法 public void FromDictionary(Dictionarystring, object rowData) { // 基础类型可以直接解析 ID Convert.ToInt32(rowData[ID]); Name rowData[Name]?.ToString() ?? string.Empty; Price Convert.ToInt32(rowData[Price]); Description rowData[Description]?.ToString() ?? string.Empty; // 枚举类型需要特殊处理 string typeStr rowData[Type]?.ToString(); if (!System.Enum.TryParse(typeStr, out Type)) { // 如果解析失败可以记录日志或设置默认值 Debug.LogWarning($无法将字符串 {typeStr} 解析为ItemType枚举ID: {ID}); Type ItemType.Material; // 默认值 } } }4.2 实现通用的反射映射器简易版对于字段不多、结构固定的配置像上面那样手动映射完全可以接受。但如果配置表很多或者字段经常增减手动映射就变得繁琐且易错。我们可以编写一个简单的反射工具来自动完成映射前提是Excel的列名与类的属性/字段名完全一致或可通过简单规则转换。using System; using System.Collections.Generic; using System.Reflection; public static class ExcelDataMapper { /// summary /// 将字典列表转换为指定类型的对象列表通过反射 /// /summary /// typeparam nameT目标类型/typeparam /// param namedataList原始字典数据列表/param /// returns转换后的对象列表/returns public static ListT MapToObjectListT(ListDictionarystring, object dataList) where T : new() { ListT result new ListT(); if (dataList null || dataList.Count 0) return result; // 获取类型T的所有公共实例属性也可以包含字段这里以属性为例 PropertyInfo[] properties typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance); FieldInfo[] fields typeof(T).GetFields(BindingFlags.Public | BindingFlags.Instance); foreach (var row in dataList) { T obj new T(); bool rowHasData false; // 映射属性 foreach (var prop in properties) { if (row.TryGetValue(prop.Name, out object value) value ! null value ! DBNull.Value) { try { // 类型转换将object转换为属性类型 object convertedValue Convert.ChangeType(value, prop.PropertyType); prop.SetValue(obj, convertedValue); rowHasData true; } catch (Exception e) { Debug.LogError($映射属性 {prop.Name} 时出错值: {value} 目标类型: {prop.PropertyType}. 错误: {e.Message}); } } } // 映射字段逻辑类似 foreach (var field in fields) { if (row.TryGetValue(field.Name, out object value) value ! null value ! DBNull.Value) { try { object convertedValue Convert.ChangeType(value, field.FieldType); field.SetValue(obj, convertedValue); rowHasData true; } catch (Exception e) { Debug.LogError($映射字段 {field.Name} 时出错值: {value} 目标类型: {field.FieldType}. 错误: {e.Message}); } } } if (rowHasData) { result.Add(obj); } } return result; } }使用方式void LoadItemConfig() { string excelPath Config/ItemConfig.xlsx; var rawData ExcelDataManager.Instance.ReadExcel(excelPath); ListItemConfig itemConfigs ExcelDataMapper.MapToObjectListItemConfig(rawData); // 现在就可以方便地使用了 foreach (var item in itemConfigs) { Debug.Log($物品: {item.Name}, 价格: {item.Price}); } }注意事项反射虽然方便但性能开销比手动映射大。对于在游戏启动时一次性加载的配置表这个开销通常可以接受。但如果需要频繁动态加载或者配置数据量极大数万行建议还是采用手动映射或者使用更高效的代码生成方案例如在编辑器模式下预生成解析代码。4.3 进阶优化使用缓存与预编译表达式树如果确实需要反射的灵活性又担心性能一个折中的方案是使用缓存和表达式树Expression Tree来优化。思路是为每种类型T只做一次反射来获取成员信息然后动态编译一个高效的赋值委托后续每行数据的映射都调用这个委托其性能接近直接赋值。这里提供一个简化概念示例using System; using System.Collections.Generic; using System.Linq.Expressions; public static class FastExcelMapper { private static DictionaryType, Delegate _mapperCache new DictionaryType, Delegate(); public static ListT MapFastT(ListDictionarystring, object dataList) where T : new() { // ... 获取或创建映射委托的逻辑 ... // 由于实现较为复杂此处不展开完整代码。核心是使用Expression.Lambda编译一个ActionT, Dictionarystring, object委托。 // 网上有许多成熟的FastMapper或ObjectMapper库实现了类似思想在Unity中也可借鉴。 } }对于大多数游戏配置读取场景基础的反射映射或手动映射已经完全够用。性能优化的首要目标永远是“先让它跑起来再在必要时优化”。5. 实战中的常见问题与排查技巧即使按照上述步骤操作在实际集成中你仍可能遇到一些“坑”。以下是我在多个项目中总结的常见问题及其解决方案。5.1 文件路径与平台兼容性问题问题描述在编辑器里运行正常打包到手机Android/iOS后读取失败。根因分析Unity中Application.streamingAssetsPath在不同平台下路径不同且访问方式也不同。编辑器和PC/Mac平台指向磁盘上的一个目录可以直接使用System.IOAPI如File.Open读取。Android平台APK包内的压缩文件不能直接使用System.IO读取。需要使用UnityWebRequest或WWW旧版来读取。iOS平台情况类似文件在只读的沙盒内但通常可以直接用System.IO读取。解决方案编写一个平台无关的文件读取工具方法。public static byte[] ReadAllBytesFromStreamingAssets(string relativePath) { string fullPath Path.Combine(Application.streamingAssetsPath, relativePath); #if UNITY_ANDROID !UNITY_EDITOR // Android特殊处理 // 方案A使用UnityWebRequest异步这里简化为同步等待实际应用建议用异步 // 方案B推荐在游戏初始化时将StreamingAssets下的配置文件复制到Application.persistentDataPath后续直接从持久化路径读取。 // 这里展示方案B的思路 string persistentPath Path.Combine(Application.persistentDataPath, relativePath); if (!File.Exists(persistentPath)) { // 首次运行从APK中复制到可读写目录 UnityEngine.Networking.UnityWebRequest www UnityEngine.Networking.UnityWebRequest.Get(fullPath); www.SendWebRequest(); while (!www.isDone) { } // 注意这里会阻塞主线程仅作示例。生产环境应用协程异步处理。 if (www.result UnityEngine.Networking.UnityWebRequest.Result.Success) { File.WriteAllBytes(persistentPath, www.downloadHandler.data); } else { Debug.LogError($无法从StreamingAssets读取文件: {fullPath}, 错误: {www.error}); return null; } } fullPath persistentPath; #endif if (File.Exists(fullPath)) { return File.ReadAllBytes(fullPath); } else { Debug.LogError($文件不存在: {fullPath}); return null; } }然后在ExcelDataManager的ReadExcel方法中将File.Open部分替换为使用上述方法获取字节数组再通过MemoryStream传递给ExcelReaderFactory.CreateReader。5.2 数据类型转换与空值处理问题描述Excel中的空单元格、数字格式的字符串如“123”、或者布尔值“TRUE”/“FALSE”在转换为C#类型时出错。排查技巧打印原始值在映射过程中先打印出row[columnName]的原始值和它的.GetType()看看ExcelDataReader究竟把它识别成了什么类型可能是double,string,DateTime, 或null。防御性编程在ExcelDataMapper的映射代码中对DBNull.Value和普通的null进行判断。使用Convert.ChangeType时用try-catch包裹并提供有意义的默认值或错误日志。处理Excel数字格式Excel中即使一个单元格显示为“001”如果它是数字格式读取出来可能就是double类型的1。如果业务上需要前导零策划应在Excel中将其设置为文本格式或者在C#端进行格式化补零。5.3 性能优化与内存管理问题描述读取一个非常大的Excel文件如10万行时速度慢甚至内存溢出。优化策略流式读取ExcelDataReader本身是流式读取但AsDataSet()方法会将整个工作表加载到内存中的DataTable。对于超大文件可以考虑使用reader.Read()方法逐行读取边读边处理而不是一次性加载全部数据。分表读取如果文件中有多个工作表但只需要其中一个不要使用reader.AsDataSet()而是用reader.ResultsCount和reader.Read()来定位到特定工作表。及时释放资源确保reader和stream在using语句块中这样即使发生异常它们也会被正确关闭和释放。缓存结果配置数据通常在游戏启动时加载一次然后在整个游戏生命周期中使用。确保你的管理器只加载一次并将结果缓存起来避免重复IO和解析操作。5.4 编辑器扩展一键导入与验证为了让策划和开发体验更好我们可以在Unity编辑器中创建一个工具窗口实现一键导入Excel并生成对应的ScriptableObject或C#数据类文件。这超出了本文动态读取的核心范畴但思路可以提一下使用UnityEditor命名空间创建自定义编辑器窗口。在窗口中提供文件选择按钮指向策划的Excel文件。使用ExcelDataReader读取文件分析表头。根据表头利用System.CodeDom或直接字符串拼接动态生成一个与Excel列对应的C#数据类脚本。或者将读取的数据直接实例化并保存为ScriptableObject资产但这又走回了老路更适合静态配置。加入数据验证逻辑例如检查ID是否重复、数值是否在合理范围等在导入阶段就发现问题。这个工具链的搭建能将“Excel配置驱动开发”的流程彻底打通极大提升团队协作效率。最后我想分享一点个人体会。从ScriptableObject转向Excel动态读取绝不仅仅是换了一个数据源。它代表着开发流程的转变策划的修改能更快地体现在游戏中版本控制变得清晰Excel文件是纯二进制或OpenXML但Git可以管理也降低了非程序人员参与游戏数据调整的门槛。虽然初期集成会遇到编码、路径、性能这些小麻烦但一旦趟平这些路带来的团队协作效率提升是巨大的。对于1252编码这种“坑”记住核心口诀“一引DLL二注编码”——引入System.Text.Encoding.CodePages.dll并在启动时调用Encoding.RegisterProvider问题便迎刃而解。