1. 项目概述为什么Unity开发者需要掌握Excel读写在游戏开发尤其是中大型商业项目里策划案、数值平衡表、多语言本地化配置甚至是关卡编辑器导出的数据最常见的载体就是Excel。你可能会想Unity不是有ScriptableObject吗为什么还要折腾Excel我干了十多年从独立小作坊到几百人的团队都待过可以很负责任地告诉你ScriptableObject是给程序员和设计师在引擎内协作的利器而Excel是策划、运营乃至发行商之间沟通的“世界语”。策划用Excel调一个怪物攻击力保存你这边游戏里实时热更这种丝滑的体验能省下无数沟通成本和重复导入导出的时间。所以“Unity项目中读写Excel文件”这个需求远不止是“把数据读进来”那么简单。它关乎工作流效率、跨部门协作甚至是线上热更新的可能性。网上一搜解决方案五花八门有推荐用EPPlus、NPOI这些.NET库的也有直接用OleDb去连的还有各种第三方插件。但很多教程要么只讲读要么写的部分一笔带过更别提在Unity特殊环境如不同平台、IL2CPP、WebGL下的各种坑了。今天我就结合自己趟过的雷给你拆解一套从原理到实践再到生产环境优化的完整方案。2. 核心方案选型插件、纯代码与混合架构的权衡面对Excel读写首先你得选条路。市面上主流就三条用现成的Unity插件、自己用纯C#库实现、或者搞一个混合架构。别急着做决定我们先来掰扯清楚各自的优劣。2.1 现成Unity插件分析很多人的第一反应是去Asset Store找插件比如“Excel To JSON”或者“Easy Save”这类带Excel功能的。它们的优点是开箱即用有可视化界面对于不熟悉代码的策划或初学者非常友好。但缺点也很明显黑盒与定制难插件内部怎么实现的你控制不了。一旦遇到一个诡异格式的Excel文件解析出错或者你需要一个特殊的数据转换逻辑很可能就得抓瞎或者等作者更新——这时间成本你耗不起。平台兼容性风险一些插件可能依赖了特定平台的本地库在Windows上跑得好好的一到Android或iOS就崩。尤其是IL2CPP编译下一些通过反射进行的动态操作可能会被剪裁掉。成本与依赖商业插件要钱而且让你的项目多了一个外部依赖。如果这个插件停止维护了将来升级Unity版本可能就是一场灾难。注意对于快速原型或小团队插件依然是可选项。但在选择前务必查看其最近更新日期、用户评价并最好在目标平台尤其是移动端和WebGL上进行测试。2.2 纯C#库方案深度解析这是追求控制和灵活性的开发者首选。核心是在Unity中使用.NET生态的库。最常被提及的两个库是NPOI 一个开源的.NET版本Java POI项目。它的最大优势是同时支持旧的.xlsHSSF和新的.xlsxXSSF格式且完全不依赖Microsoft Office或ACE引擎纯托管代码实现。这意味着它在所有Unity支持的平台上都有良好的一致性。EPPlus 起初是开源库用于处理.xlsxOffice Open XML格式。它API设计优雅读写性能优秀但对.xls格式不支持。需要注意的是EPPlus在较新的版本中5.0采用了双许可证商业用途需要购买许可证这在选择时是个重要考量。为什么我最终倾向推荐NPOI在游戏开发中你无法保证策划永远用最新版Office保存为.xlsx。经常会有历史遗留的.xls文件或者从其他工具导出的.xls。NPOI的格式全覆盖能力消除了这个风险。其次它的开源协议Apache License 2.0对商业应用友好没有潜在的法律风险。虽然API可能比EPPlus稍显“原始”但稳定性和兼容性在跨平台场景下是第一位的。2.3 混合架构设计思路这是我在大型项目中更推崇的模式“解析与逻辑分离”。简单说就是专门做一个独立的工具可以是控制台程序也可以是Unity Editor下的一个工具窗口用NPOI这样的库把Excel文件读取出来然后转换成一种Unity更易处理、且与平台无关的中间格式——通常是JSON或二进制文件。这个工具只在编辑阶段运行。游戏运行时Unity只需要加载和解析这个JSON或二进制文件即可。这样做的好处爆炸式增长安全与性能 运行时完全剥离了对复杂Excel解析库的依赖安装包更小内存占用更少也没有了因Excel文件格式错误导致游戏崩溃的风险。二进制格式的读取速度远超解析Excel。热更新友好 你可以轻松地将生成的JSON或二进制数据文件放在服务器上。游戏启动时或需要时下载最新数据实现数值、文案的不更新客户端热更这是运营活动的神器。职责分离 策划只管改Excel工具自动打包程序只管读优化后的数据文件。双方通过定义好的数据Schema比如一个C#数据类来约定协作流畅互不干扰。接下来的实操我们将以NPOI为核心同时贯彻混合架构的思想带你走通全流程。3. 实战准备在Unity中集成与使用NPOI理论说完我们动手。首先你需要把NPOI弄到你的Unity项目里。3.1 获取与导入NPOI不建议直接下载DLL因为要处理依赖关系。最稳妥的方式是通过Unity的包管理器Package Manager使用NuGet或者从GitHub获取源码。方法一使用NuGet For Unity推荐从Asset Store或GitHub获取并安装“NuGet For Unity”这个插件。在Unity中打开菜单NuGet-Manage NuGet Packages。在搜索框中输入“NPOI”找到并安装NPOI官方包。NuGet会自动处理其依赖如SharpZipLib等。安装完成后相关的DLL会出现在项目的Packages文件夹内Unity会自动将其引用。方法二手动导入DLL备用前往NPOI的GitHub发布页下载最新的稳定版-bin.zip压缩包。解压后你需要将以下核心DLL文件复制到你Unity项目的Assets/Plugins文件夹下如果没有就新建NPOI.dllNPOI.OOXML.dll(用于xlsx)NPOI.OpenXml4Net.dll(用于xlsx)NPOI.OpenXmlFormats.dll(用于xlsx)ICSharpCode.SharpZipLib.dll(依赖项)如果还需要支持.xls则还需要NPOI.HSSF.dll(用于xls)NPOI.DDF.dll(用于xls)NPOI.Util.dll实操心得务必检查DLL的.NET版本兼容性。NPOI通常面向.NET Standard 2.0这与Unity现代版本是兼容的。如果遇到运行时错误尝试将DLL放入Assets/Plugins下的子文件夹如Assets/Plugins/NPOI并确保在Player Settings中这些DLL被正确包含在目标平台的构建中。3.2 定义数据模型Schema先行在读写之前我们必须知道Excel里数据的结构。这是混合架构中“约定”的部分。假设我们有一个策划表Monster.xlsx结构如下IDNameHPAttackPrefabPath1001史莱姆5010Prefabs/Monster/Slime1002骷髅兵8015Prefabs/Monster/Skeleton我们需要一个对应的C#类来映射它// MonsterData.cs [System.Serializable] // 使其可被JsonUtility序列化 public class MonsterData { public int ID; public string Name; public int HP; public int Attack; public string PrefabPath; // 资源路径 } // 用于存储整个表 [System.Serializable] public class MonsterDataTable { public ListMonsterData dataList new ListMonsterData(); }这个MonsterData类就是我们的Schema。策划的Excel列名需要与这个类的字段名对应或者通过映射关系这样转换工具才能正确工作。4. 核心实现Excel读取、转换与写入详解现在进入核心环节。我们将分别实现一个编辑器工具来读取Excel并生成JSON以及一个运行时加载JSON的管理器。4.1 编辑器工具开发Excel转JSON在Unity Editor下创建一个工具脚本比如ExcelToJsonConverter.cs放在Assets/Editor目录下。// ExcelToJsonConverter.cs using UnityEngine; using UnityEditor; using System.IO; using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; // for .xlsx using NPOI.HSSF.UserModel; // for .xls using System.Collections.Generic; public static class ExcelToJsonConverter { [MenuItem(Tools/Excel/Convert Selected Excel to JSON)] public static void ConvertSelectedExcel() { // 1. 获取在Project窗口选中的Excel文件 Object selected Selection.activeObject; if (selected null) { EditorUtility.DisplayDialog(错误, 请先在Project窗口选择一个Excel文件, 确定); return; } string excelPath AssetDatabase.GetAssetPath(selected); if (!excelPath.EndsWith(.xlsx) !excelPath.EndsWith(.xls)) { EditorUtility.DisplayDialog(错误, 选中的文件不是Excel文件 (.xlsx 或 .xls), 确定); return; } // 2. 使用NPOI打开工作簿 IWorkbook workbook; using (FileStream fileStream new FileStream(excelPath, FileMode.Open, FileAccess.Read)) { if (excelPath.EndsWith(.xlsx)) workbook new XSSFWorkbook(fileStream); else workbook new HSSFWorkbook(fileStream); } // 3. 处理第一个工作表 (可以根据需要遍历多个Sheet) ISheet sheet workbook.GetSheetAt(0); // 假设第一行是列标题 IRow headerRow sheet.GetRow(0); if (headerRow null) return; // 4. 读取数据行构建数据列表 ListDictionarystring, object rowDataList new ListDictionarystring, object(); for (int rowIndex 1; rowIndex sheet.LastRowNum; rowIndex) // 从第2行开始读数据 { IRow dataRow sheet.GetRow(rowIndex); if (dataRow null) continue; Dictionarystring, object rowData new Dictionarystring, object(); for (int colIndex 0; colIndex headerRow.LastCellNum; colIndex) { string header headerRow.GetCell(colIndex)?.ToString()?.Trim(); ICell dataCell dataRow.GetCell(colIndex); object cellValue GetCellValue(dataCell); // 自定义方法处理不同类型值 if (!string.IsNullOrEmpty(header)) { rowData[header] cellValue; } } if (rowData.Count 0) rowDataList.Add(rowData); } // 5. 将数据列表序列化为JSON // 这里需要根据你的数据模型来调整。简单演示直接序列化字典列表。 string json JsonUtility.ToJson(new SerializationWrapper(rowDataList), true); // 美化输出 // 6. 保存JSON文件到相同目录 string jsonFilePath Path.ChangeExtension(excelPath, .json); File.WriteAllText(jsonFilePath, json); AssetDatabase.Refresh(); // 刷新Unity资源数据库 Debug.Log($转换成功JSON文件已保存至: {jsonFilePath}); } // 处理单元格值的辅助方法 private static object GetCellValue(ICell cell) { if (cell null) return null; switch (cell.CellType) { case CellType.Numeric: // 判断是否为日期格式 if (DateUtil.IsCellDateFormatted(cell)) return cell.DateCellValue; else return cell.NumericCellValue; case CellType.String: return cell.StringCellValue?.Trim(); case CellType.Boolean: return cell.BooleanCellValue; case CellType.Formula: // 对于公式可以尝试获取缓存的计算值或者重新计算复杂 // 简单处理返回公式字符串或尝试获取计算后的值 try{ return cell.NumericCellValue; // 尝试获取数值结果 }catch{ return cell.StringCellValue; } case CellType.Blank: default: return null; } } // 因为JsonUtility不能直接序列化ListDictionary需要一个包装类 [System.Serializable] private class SerializationWrapper { public ListDictionarystring, object items; public SerializationWrapper(ListDictionarystring, object list) { items list; } } }这个工具提供了一个菜单项选中Excel文件后一键转换为JSON。GetCellValue方法处理了数字、字符串、布尔值、日期和公式等不同类型这是解析准确的关键。4.2 运行时数据加载与管理JSON文件生成后在游戏运行时加载就非常简单高效了。我们可以创建一个数据管理器。// DataManager.cs using UnityEngine; using System.IO; using System.Collections.Generic; public class DataManager : MonoBehaviour { private static DataManager _instance; public static DataManager Instance _instance; private Dictionaryint, MonsterData _monsterDataDict new Dictionaryint, MonsterData(); void Awake() { if (_instance ! null _instance ! this) { Destroy(gameObject); return; } _instance this; DontDestroyOnLoad(gameObject); LoadMonsterData(); } void LoadMonsterData() { // 假设JSON文件放在 Resources 文件夹下或通过Addressables/AssetBundle加载 TextAsset jsonText Resources.LoadTextAsset(Data/Monster); if (jsonText null) { Debug.LogError(未找到怪物数据JSON文件); return; } // 反序列化 MonsterDataTable table JsonUtility.FromJsonMonsterDataTable(jsonText.text); foreach (var data in table.dataList) { _monsterDataDict[data.ID] data; } Debug.Log($已加载 {_monsterDataDict.Count} 条怪物数据。); } public MonsterData GetMonsterData(int id) { if (_monsterDataDict.TryGetValue(id, out MonsterData data)) return data; Debug.LogWarning($未找到ID为 {id} 的怪物数据。); return null; } }4.3 进阶Excel写入与数据回导有时我们需要将游戏内的数据如玩家编辑的配置写回Excel。这个过程是读取的逆过程。// 在Editor工具中添加一个写回功能 public static void WriteDataToExcel(string templatePath, ListMonsterData dataList, string outputPath) { IWorkbook workbook; using (FileStream fs new FileStream(templatePath, FileMode.Open, FileAccess.Read)) { workbook new XSSFWorkbook(fs); // 基于模板创建 } ISheet sheet workbook.GetSheetAt(0); // 假设模板第一行是标题行 // 从第二行开始写入数据 for (int i 0; i dataList.Count; i) { IRow row sheet.GetRow(i 1) ?? sheet.CreateRow(i 1); // 获取或创建行 MonsterData data dataList[i]; // 根据标题行映射写入对应单元格 // 这里需要你事先知道列顺序或通过标题名查找列索引 row.CreateCell(0).SetCellValue(data.ID); row.CreateCell(1).SetCellValue(data.Name); row.CreateCell(2).SetCellValue(data.HP); row.CreateCell(3).SetCellValue(data.Attack); row.CreateCell(4).SetCellValue(data.PrefabPath); } using (FileStream fs new FileStream(outputPath, FileMode.Create, FileAccess.Write)) { workbook.Write(fs); } Debug.Log($数据已写入Excel: {outputPath}); }5. 平台适配、性能优化与避坑指南理论能跑通但上真机、上WebGL才是考验的开始。下面是我踩过坑后总结的要点。5.1 各平台兼容性关键点PC/Windows/Mac 通常问题最少NPOI的纯托管代码实现可以完美运行。Android/iOS IL2CPP是最大的挑战。NPOI内部大量使用反射和动态代码生成这可能会被IL2CPP的代码剪裁Stripping破坏。解决方案在Project Settings - Player - Other Settings中将Managed Stripping Level设置为Low或Minimal。创建link.xml文件放在Assets根目录用于告诉IL2CPP不要剪裁NPOI相关的程序集和类型。这是一个复杂的过程需要你分析NPOI用到了哪些依赖。最根本的解决之道采用混合架构。只在Editor下使用NPOI运行时只加载JSON/二进制数据彻底规避此问题。这是我最推荐的生产环境做法。WebGL 情况类似移动端且限制更多。在WebGL下直接使用System.IO操作本地文件系统是不行的。同样混合架构是必选项。Excel转JSON的过程在构建前完成JSON文件作为资源打包。如果需从服务器动态更新数据通过UnityWebRequest下载JSON文本即可。5.2 性能优化策略二进制替代JSON 当数据量极大数万行时JSON的文本解析JsonUtility/Newtonsoft.Json会成为性能瓶颈和内存负担。可以考虑将数据序列化为二进制格式。可以使用C#的BinaryFormatter已过时不推荐或更高效的第三方库如MessagePack、Protobuf-net。它们能极大减少文件体积加快加载速度。按需加载与分块 不要一次性加载所有配置表。将数据按功能模块分表并实现按需加载和卸载。例如只有进入战斗场景时才加载怪物表和技能表。内存复用与缓存 对于频繁访问的配置数据在内存中缓存反序列化后的C#对象避免重复解析。5.3 常见问题与排查技巧实录下面这个表格是我和同事们在实际开发中遇到的一些典型问题及解决方法希望能帮你节省大量调试时间。问题现象可能原因排查与解决思路在Editor中读取正常打包后尤其是移动端报错“DLLNotFoundException”或“TypeLoadException”IL2CPP代码剪裁掉了NPOI必要的类型或方法。1. 首先确认是否必须运行时读取Excel。强烈建议转为混合架构。2. 如果必须用降低Managed Stripping Level并精心配置link.xml。3. 尝试使用NPOI的源码而非DLL并将必要源码直接放入项目避免剪裁。读取Excel数字日期变成了浮点数Excel内部将日期存储为“序列号”从1899-12-30开始的天数。使用NPOI的DateUtil.IsCellDateFormatted(cell)判断并用cell.DateCellValue获取正确的DateTime对象。读取的字符串首尾有空白字符或不可见字符策划在Excel单元格中不小心输入了空格或换行符。在读取单元格字符串后立即使用.Trim()方法清理。cell.StringCellValue?.Trim()。公式单元格读取不到计算结果cell.CellType是Formula直接取StringCellValue拿到的是公式字符串。尝试使用cell.NumericCellValue或cell.StringCellValue但前提是Excel文件已缓存计算结果。更可靠的方式是在工具中让策划将公式“粘贴为值”后再导出。生成的JSON文件在Unity中无法被JsonUtility反序列化JsonUtility要求顶级对象必须是简单类且字段需标记[System.Serializable]。确保你的包装类如MonsterDataTable和内部类MonsterData都标记了[System.Serializable]且字段为public或标记了[SerializeField]。对于复杂结构字典列表需要像示例中那样使用包装类。WebGL平台上无法从本地路径读取Excel文件WebGL的安全限制无法直接访问本地文件系统。设计上就应避免。构建前完成Excel到JSON的转换。运行时数据来自Resources、Addressables或网络下载。如果必须在WebGL中让用户上传Excel使用UnityEngine.WebGLFileUploader或通过HTML的input type”file”配合JS交互来获取文件字节流再在内存中用NPOI解析。此路径非常复杂非必要不推荐。6. 生产环境增强自动化流水线与扩展思考对于团队协作手动点击菜单转换是不可靠的。我们需要自动化。6.1 集成到CI/CD或自动化构建流程你可以创建一个命令行工具或者直接扩展上面的Editor脚本使其能在构建前自动执行。// 在Editor脚本中添加一个被PostProcessBuild调用的方法 public class BuildExcelProcessor { [InitializeOnLoadMethod] public static void RegisterBuildCallback() { BuildPlayerWindow.RegisterBuildPlayerHandler(BuildPlayerHandler); } private static void BuildPlayerHandler(BuildPlayerOptions options) { // 1. 在构建前执行所有Excel转换 Debug.Log(开始自动转换Excel数据...); ConvertAllExcelInFolder(Application.dataPath /Resources/Data/Excel/); // 2. 继续原有构建流程 BuildPipeline.BuildPlayer(options); } static void ConvertAllExcelInFolder(string folderPath) { // 遍历文件夹找到所有.xlsx/.xls文件并调用转换逻辑 // ... } }这样每次打包时都会自动将最新的Excel数据转换为游戏可用的格式确保数据同步。6.2 扩展思考更复杂的数据结构现实中的配置表往往更复杂多Sheet表 遍历workbook.GetSheetAt(i)或通过名称workbook.GetSheet(“SheetName”)获取。嵌套结构如数组、字典 在Excel中可以用特定分隔符如逗号、分号存储在一个单元格内读取后用string.Split解析。或者用多行来表示一条记录的多个属性这需要更复杂的解析逻辑。数据类型校验 在转换工具中加入校验逻辑检查ID是否重复、数值是否越界、资源路径是否存在等及早发现策划配置错误。版本管理与差异更新 为生成的数据文件附加版本号或哈希值。客户端加载时与服务器上的版本对比实现增量更新减少玩家下载流量。我个人在实际项目中的体会是Excel读写这个模块初期花点时间搭建一个稳健的、自动化的工作流后期会节省整个团队海量的时间。它不仅仅是技术实现更是项目管理与协作效率的体现。从最初的手动复制粘贴到后来的半自动工具再到如今的全自动流水线集成每一次升级带来的都是更少的错误和更快的迭代速度。记住好的工具是让策划感觉不到工具的存在数据修改能自然而安全地反映到游戏中这才是成功的标志。