1. 项目概述与核心价值在Unity3D项目开发中尤其是涉及游戏配置、关卡数据、本地化文本或者玩家数据存档时我们常常需要处理结构化数据。虽然Unity自带的ScriptableObject和JSON序列化非常方便但在很多实际工作流中策划、运营或非技术同事更习惯使用Excel来编辑和维护这些数据。因此实现Unity3D与Excel文件的动态交互就成了一个连接开发管线与内容生产环节的刚需。这个需求的核心不仅仅是“能读写”更是要“在运行时动态创建、写入并能被Excel正常打开”同时还要兼顾跨平台兼容性、性能以及避免引入复杂的依赖。网上相关的讨论很多但坑也不少。就像我最初尝试时一样兴冲冲地引入了某个看起来功能强大的第三方Excel库结果Unity直接报错提示找不到命名空间或者构建到移动平台时直接崩溃。这背后的原因在于很多为.NET Framework设计的Excel库严重依赖Windows系统组件或特定的运行时环境这与Unity基于Mono或IL2CPP的跨平台运行时天生不兼容。所以这个教程的目的就是带你绕开这些坑找到在Unity中实现Excel读写特别是动态创建与写入的可靠、实用的方案。无论你是想制作一个由Excel驱动关卡数据的独立游戏还是需要为工具链开发一个数据导出功能这篇文章都能给你一套经过验证的、可直接落地的代码和思路。2. 方案选型为什么放弃“重量级”库选择“轻量级”协议在动手写代码之前我们先来彻底搞清楚方案选型的逻辑。为什么社区里普遍不推荐直接在Unity里用类似Microsoft.Office.Interop.Excel或者Aspose.Cells这样的库这不仅仅是“能不能用”的问题更是“好不好用”、“稳不稳定”的根本性问题。2.1 剖析传统Excel库的兼容性陷阱以Microsoft.Office.Interop.Excel为例它本质上是一组COM接口的封装要求你的运行环境中必须安装有完整版本的Microsoft Excel。这在Windows PC上开发时或许能跑起来但一旦你尝试构建项目到其他平台比如iOS、Android、WebGL或者甚至是没有安装Excel的Windows PC上程序会立刻崩溃。因为它依赖的COM组件和Excel可执行文件根本不存在于目标平台。这完全违背了Unity“一次编写多平台部署”的核心优势。另一个常见选择是Aspose.Cells或EPPlus等第三方商业或开源库。这些库功能确实强大支持复杂的格式、公式、图表。但问题同样出在依赖和运行时上。许多这类库为了高性能底层使用了.NET Framework中的一些特定API如System.Drawing或者原生的互操作这些在Unity的裁剪后运行时尤其是IL2CPP中可能无法正常工作或者需要引入额外的、可能不稳定的C插件。此外它们的程序集通常较大会增加最终构建包的体积。从网络讨论中那位开发者遇到的“Unity突然丢失库引用”的错误来看这种不稳定的兼容性问题在实践中非常普遍。2.2 CSV与JSON轻量级替代方案的优劣对比于是社区的主流建议转向了更简单的文本格式CSV和JSON。CSV逗号分隔值文件本质上是纯文本用逗号或制表符分隔数据。它的最大优势是极度简单任何文本编辑器都能打开Excel也能直接导入和保存。在Unity中使用System.IO命名空间下的StreamReader和StreamWriter就能轻松读写零依赖全平台兼容。对于仅仅是存储表格数据行和列的场景CSV几乎是最佳选择。但是它的缺点也很明显它无法存储复杂的格式如单元格颜色、字体、多工作表Sheet、合并单元格或公式。数据如果包含逗号或换行符还需要额外的转义处理。JSON是另一种优秀的轻量级数据交换格式。它结构清晰嵌套灵活非常适合表示复杂的、层次化的数据比如一个角色的所有属性包含装备列表、技能树等。Unity对JSON有原生支持通过JsonUtility或第三方库如Newtonsoft.Json序列化和反序列化非常方便。然而JSON文件对于非技术背景的策划或运营人员来说直接编辑并不友好它缺乏Excel那种直观的表格视图。2.3 核心思路分离数据编辑与运行时使用基于以上分析一个健壮的、适用于生产环境的方案其核心思路应该是“编辑时用Excel运行时用中间格式”。策划/运营在熟悉的Excel中编辑数据利用其强大的格式、公式、数据验证等功能。开发管线通过一个编辑器工具Editor Script将Excel文件.xlsx或.xls在Unity编辑器中转换为游戏运行时易于加载的格式如JSON、二进制文件或直接注入到ScriptableObject中。游戏运行时Unity程序只加载处理好的JSON或二进制数据完全摆脱对Excel库的依赖。这个流程完美解决了兼容性和易用性的矛盾。我们只需要在Unity编辑器环境下解决Excel读取问题而编辑器环境是相对可控的Windows/macOS系统。对于动态“写入”Excel的需求通常也发生在这个编辑器工具环节比如将游戏内的配置或统计结果导出成一份给策划看的Excel报告。因此本教程将聚焦于实现这一流程的两个关键部分一是在Unity编辑器下可靠地读取和写入.xlsx文件二是在游戏运行时如何设计数据结构和流程来支持类似“动态创建数据表并导出”的需求。3. 实战准备选择与集成可靠的Excel操作库既然确定了主战场在编辑器下我们就可以选择一个专为.NET环境设计、不依赖Office安装、且与Unity兼容性较好的库。这里我强烈推荐EPPlus。这是一个开源从5.0开始使用Polyform Noncommercial License需注意商业用途许可且功能强大的.NET库专门用于操作Open Office XML格式即.xlsx。它不需要安装Excel纯托管代码实现在Unity的编辑器脚本中使用非常稳定。3.1 在Unity中安装EPPlusEPPlus通常以DLL的形式提供。最稳妥的获取方式是通过其GitHub仓库发布页下载编译好的.NET Standard 2.0版本DLL这个版本与Unity的兼容性最好。下载DLL访问EPPlus的GitHub仓库在Releases页面找到并下载EPPlus.xxx.zip文件。解压后找到名为EPPlus.dll的核心文件。导入Unity在你的Unity项目Assets目录下创建一个名为Plugins的文件夹如果不存在。将EPPlus.dll复制到Assets/Plugins目录下。Unity会自动识别并导入它。处理依赖EPPlus 5.0版本可能依赖System.Drawing.Common。对于Unity 2020及以上版本基于.NET Standard 2.1或.NET Framework 4.x这个依赖通常已包含。如果遇到缺失System.Drawing相关错误你可能需要从NuGet或其他来源获取System.Drawing.Common.dll同样放入Plugins文件夹。注意务必确保你下载的是适用于.NET Standard 2.0的版本。直接使用针对完整.NET Framework的DLL可能在Unity中引发运行时错误。将DLL放入Plugins文件夹是关键这能确保Unity在编译编辑器脚本时正确引用它。3.2 验证安装与基础读写测试创建一个新的C#脚本命名为ExcelEditorTool.cs将其放在Assets/Editor目录下确保它只在编辑器环境下运行。using UnityEngine; using UnityEditor; using System.IO; // 引入EPPlus命名空间 using OfficeOpenXml; public class ExcelEditorTool : EditorWindow { [MenuItem(Tools/Excel/Test EPPlus)] static void TestEPPlusConnection() { // 创建一个全新的Excel包在内存中 using (ExcelPackage excelPackage new ExcelPackage()) { // 添加一个工作表 ExcelWorksheet worksheet excelPackage.Workbook.Worksheets.Add(TestSheet); // 向单元格写入数据 worksheet.Cells[1, 1].Value Hello; worksheet.Cells[1, 2].Value Unity; worksheet.Cells[2, 1].Value 42; worksheet.Cells[2, 2].Formula A2*2; // 甚至支持公式 // 设置单元格样式 worksheet.Cells[1, 1, 1, 2].Style.Font.Bold true; worksheet.Cells[2, 1].Style.Numberformat.Format 0.00; // 定义保存路径在项目Assets目录外避免Unity自动导入 string savePath Path.Combine(Application.dataPath, .., TestOutput.xlsx); // 将Excel包保存为文件 FileInfo excelFile new FileInfo(savePath); excelPackage.SaveAs(excelFile); Debug.Log($测试Excel文件已生成: {savePath}); EditorUtility.RevealInFinder(savePath); // 在文件管理器中打开所在文件夹 } } }点击Unity编辑器菜单栏的Tools/Excel/Test EPPlus。如果一切顺利你会在项目上一级目录看到生成的TestOutput.xlsx文件用Excel打开它你会看到“Hello”和“Unity”两个加粗的单元格以及一个数字和公式。这个测试成功意味着EPPlus已经在你的Unity编辑器中正常工作为我们后续的所有操作打下了基础。这个简单的测试也展示了EPPlus的核心对象模型ExcelPackage代表整个工作簿ExcelWorksheet代表单个工作表Cells[row, col]用于访问和操作单元格。4. 核心模块一编辑器工具——从Excel到游戏数据这是自动化管线的核心。我们将创建一个功能完整的编辑器窗口用于将策划配置的Excel表格一键转换为Unity游戏可用的数据资产ScriptableObject或JSON文件。4.1 设计可配置的转换映射规则策划的Excel表格结构多样我们需要一个灵活的方式来定义“Excel中的哪一列对应游戏数据类的哪个属性”。为此我们创建一个配置类ExcelImportConfig。using UnityEngine; using System; [CreateAssetMenu(fileName NewExcelConfig.asset, menuName Game/Excel Import Config)] public class ExcelImportConfig : ScriptableObject { public string excelFilePath; // Excel文件的相对路径如Assets/Config/Levels.xlsx public string worksheetName Sheet1; // 要读取的工作表名 public bool hasHeaderRow true; // 第一行是否为标题行 public int dataStartRow 2; // 数据开始的行号如果标题行是第1行这里就是2 // 列映射Excel列索引1-based - 数据类属性名 public ColumnMapping[] columnMappings; [Serializable] public class ColumnMapping { public int excelColumnIndex; // Excel中的列号A1, B2... public string dataFieldName; // 对应C#数据类中的字段名 public string dataFieldType; // 字段类型如int, float, string, bool } // 输出的数据容器ScriptableObject的预制类型 public ScriptableObject outputDataContainerTemplate; // 或输出为JSON文件的路径 public string jsonOutputPath; }这个配置资产允许策划或开发者通过Unity Inspector界面直观地设置转换规则。例如一个关卡配置表第1列ID映射到LevelData类的id字段int类型第2列关卡名映射到name字段string类型。4.2 实现通用的Excel解析与转换引擎接下来我们实现一个强大的ExcelImporter类它利用EPPlus读取Excel并根据上述配置进行转换。using OfficeOpenXml; using System; using System.Collections.Generic; using System.IO; using UnityEngine; public static class ExcelImporter { public static ListT ImportFromExcelT(ExcelImportConfig config) where T : new() { ListT dataList new ListT(); FileInfo excelFile new FileInfo(Path.Combine(Application.dataPath, .., config.excelFilePath)); if (!excelFile.Exists) { Debug.LogError($Excel文件不存在: {excelFile.FullName}); return dataList; } using (ExcelPackage excelPackage new ExcelPackage(excelFile)) { ExcelWorksheet worksheet excelPackage.Workbook.Worksheets[config.worksheetName]; if (worksheet null) { Debug.LogError($在工作簿中未找到工作表: {config.worksheetName}); return dataList; } int startRow config.hasHeaderRow ? config.dataStartRow : 1; int row startRow; // 循环读取每一行直到遇到第一个所有映射列都为空的单元格视为数据结束 while (true) { bool rowHasData false; T dataItem new T(); var dataType typeof(T); foreach (var mapping in config.columnMappings) { int col mapping.excelColumnIndex; var cell worksheet.Cells[row, col]; object cellValue cell.Value; if (cellValue ! null !string.IsNullOrWhiteSpace(cellValue.ToString())) { rowHasData true; } // 将单元格值转换为目标类型并赋值 try { var field dataType.GetField(mapping.dataFieldName); if (field ! null) { object convertedValue ConvertCellValue(cellValue, mapping.dataFieldType); field.SetValue(dataItem, convertedValue); } } catch (Exception e) { Debug.LogWarning($第{row}行第{col}列映射到{mapping.dataFieldName}数据转换失败: {e.Message}); } } if (!rowHasData) { break; // 遇到空行停止读取 } dataList.Add(dataItem); row; } } Debug.Log($从 {config.excelFilePath} 成功导入 {dataList.Count} 条数据到类型 {typeof(T).Name}。); return dataList; } private static object ConvertCellValue(object cellValue, string targetType) { if (cellValue null) return GetDefaultValue(targetType); string stringValue cellValue.ToString(); switch (targetType.ToLower()) { case int: if (int.TryParse(stringValue, out int intResult)) return intResult; return 0; case float: if (float.TryParse(stringValue, out float floatResult)) return floatResult; return 0f; case bool: // 支持1/0, true/false, 是/否等多种布尔表示 if (int.TryParse(stringValue, out int intBool)) return intBool ! 0; if (bool.TryParse(stringValue, out bool boolResult)) return boolResult; return stringValue.Equals(是, StringComparison.OrdinalIgnoreCase); case string: default: return stringValue; } } private static object GetDefaultValue(string type) { switch (type.ToLower()) { case int: return 0; case float: return 0f; case bool: return false; default: return null; } } }这个导入器的核心是一个泛型方法它可以自动将Excel行映射到任何你定义的C#数据类通过where T : new()约束。ConvertCellValue方法处理了类型转换的细节增强了鲁棒性。在实际项目中你可能还需要处理更复杂的类型如枚举、数组可以用特定分隔符如分号存储在一格内、甚至对其它数据行的引用。4.3 构建易用的编辑器界面与自动化流程最后我们将配置和导入逻辑整合到一个用户友好的编辑器窗口中。using UnityEditor; using UnityEngine; using System.Collections.Generic; using System.IO; public class ExcelImportWindow : EditorWindow { private ExcelImportConfig currentConfig; private Vector2 scrollPos; private string statusMessage ; private MessageType statusType MessageType.None; [MenuItem(Tools/Excel/Import Window)] static void Init() { GetWindowExcelImportWindow(Excel导入工具).Show(); } void OnGUI() { scrollPos EditorGUILayout.BeginScrollView(scrollPos); // 1. 选择或创建配置 EditorGUILayout.LabelField(配置设置, EditorStyles.boldLabel); currentConfig (ExcelImportConfig)EditorGUILayout.ObjectField(导入配置, currentConfig, typeof(ExcelImportConfig), false); if (currentConfig null) { if (GUILayout.Button(创建新配置)) { string path EditorUtility.SaveFilePanelInProject(保存配置, ExcelImportConfig, asset, 请选择保存位置); if (!string.IsNullOrEmpty(path)) { currentConfig CreateInstanceExcelImportConfig(); AssetDatabase.CreateAsset(currentConfig, path); AssetDatabase.Refresh(); } } EditorGUILayout.EndScrollView(); return; } // 2. 绘制配置详情 EditorGUI.BeginChangeCheck(); SerializedObject so new SerializedObject(currentConfig); SerializedProperty sp so.FindProperty(excelFilePath); EditorGUILayout.PropertyField(sp); // ... 绘制其他属性如worksheetName, hasHeaderRow等 // 动态绘制ColumnMapping数组 sp so.FindProperty(columnMappings); EditorGUILayout.PropertyField(sp, true); if (EditorGUI.EndChangeCheck()) { so.ApplyModifiedProperties(); EditorUtility.SetDirty(currentConfig); } EditorGUILayout.Space(20); // 3. 操作按钮 EditorGUILayout.LabelField(操作, EditorStyles.boldLabel); if (GUILayout.Button(预览Excel前5行, GUILayout.Height(30))) { PreviewExcelData(); } if (GUILayout.Button(执行导入 (生成ScriptableObject), GUILayout.Height(40))) { ImportToScriptableObject(); } if (GUILayout.Button(执行导入 (生成JSON文件), GUILayout.Height(40))) { ImportToJson(); } // 4. 状态显示 if (!string.IsNullOrEmpty(statusMessage)) { EditorGUILayout.HelpBox(statusMessage, statusType); } EditorGUILayout.EndScrollView(); } void PreviewExcelData() { // 使用EPPlus读取文件获取指定工作表的前几行数据并在窗口中显示。 // 这能帮助用户确认列映射是否正确。 statusMessage 预览功能待实现。请先手动用Excel打开文件核对列结构。; statusType MessageType.Info; } void ImportToScriptableObject() { if (currentConfig.outputDataContainerTemplate null) { statusMessage 错误请先配置‘输出数据容器模板’。; statusType MessageType.Error; return; } // 这里假设模板是一个包含ListT的ScriptableObject。 // 1. 使用ExcelImporter.ImportFromExcelT导入数据列表。 // 2. 实例化模板将数据列表赋值给它。 // 3. 使用AssetDatabase.CreateAsset保存为新的.asset文件。 statusMessage 导入成功已生成ScriptableObject数据资产。; statusType MessageType.Info; } void ImportToJson() { if (string.IsNullOrEmpty(currentConfig.jsonOutputPath)) { statusMessage 错误请先配置‘JSON输出路径’。; statusType MessageType.Error; return; } // 1. 使用ExcelImporter.ImportFromExcelT导入数据列表。 // 2. 使用JsonUtility.ToJson将列表序列化为JSON字符串。 // 3. 使用File.WriteAllText写入到配置的路径。 statusMessage 导入成功已生成JSON数据文件。; statusType MessageType.Info; } }这个窗口提供了完整的GUI加载配置、编辑映射规则、执行导入。PreviewExcelData函数可以进一步扩展用DataGrid之类的控件显示读取的原始数据让映射配置过程更加直观。通过这样的工具策划只需维护Excel文件开发者一键即可将其同步到游戏项目中极大地提升了协作效率和数据一致性。5. 核心模块二运行时逻辑——动态数据收集与导出虽然游戏运行时不应依赖Excel库但“动态创建数据并导出为Excel”的需求是真实存在的例如导出玩家行为日志、生成关卡编辑器的数据模板、输出游戏内经济系统统计报表等。这里的“动态创建”指的是在游戏运行过程中或通过一个特殊的“导出模式”程序收集数据并在编辑器环境或PC独立构建中调用EPPlus生成Excel文件。5.1 设计运行时数据收集器首先我们需要一个与游戏逻辑解耦的数据收集系统。它不关心数据最终是写成Excel、JSON还是上传到服务器只负责按照定义好的格式收集数据。using System; using System.Collections.Generic; // 定义一个通用的数据行 public class DataRow { public Listobject Values { get; private set; } new Listobject(); public void AddValue(object value) { Values.Add(value); } } // 定义一个数据表包含列头和多行数据 public class DataTable { public string TableName { get; set; } public Liststring Headers { get; private set; } new Liststring(); public ListDataRow Rows { get; private set; } new ListDataRow(); public DataRow CreateRow() { DataRow row new DataRow(); Rows.Add(row); return row; } // 添加一行数据参数顺序对应列顺序 public void AddRow(params object[] values) { DataRow row CreateRow(); foreach (var v in values) { row.AddValue(v); } } } // 运行时数据收集管理器单例示例 public class RuntimeDataCollector : MonoBehaviour { private static RuntimeDataCollector _instance; public static RuntimeDataCollector Instance _instance; private Dictionarystring, DataTable _tables new Dictionarystring, DataTable(); void Awake() { if (_instance ! null _instance ! this) { Destroy(gameObject); return; } _instance this; DontDestroyOnLoad(gameObject); } public DataTable GetOrCreateTable(string tableName) { if (!_tables.ContainsKey(tableName)) { _tables[tableName] new DataTable { TableName tableName }; } return _tables[tableName]; } // 示例收集玩家每局游戏数据 public void RecordGameSession(string playerId, int score, float playTime, string levelName) { var table GetOrCreateTable(GameSessions); if (table.Headers.Count 0) { table.Headers.AddRange(new[] { 时间戳, 玩家ID, 得分, 游戏时长(秒), 关卡名 }); } table.AddRow(DateTime.Now.ToString(yyyy-MM-dd HH:mm:ss), playerId, score, playTime, levelName); } public void ClearTable(string tableName) { if (_tables.ContainsKey(tableName)) { _tables[tableName].Rows.Clear(); } } public void ClearAll() { _tables.Clear(); } }这个收集器非常轻量只在内存中维护数据。游戏逻辑在任何地方都可以调用RuntimeDataCollector.Instance.RecordGameSession(...)来记录数据。所有数据按表组织便于后续按不同主题导出。5.2 实现跨平台的导出触发机制接下来是关键如何安全地触发Excel导出由于EPPlus不能在iOS/Android等平台的运行时使用我们必须通过条件编译将导出逻辑隔离。using UnityEngine; using System.IO; #if UNITY_EDITOR using OfficeOpenXml; #endif public class RuntimeDataExporter : MonoBehaviour { // 提供给游戏内UI按钮调用的方法 public void ExportAllDataToExcel() { string fileName $GameData_Export_{System.DateTime.Now:yyyyMMdd_HHmmss}.xlsx; // 在PC上保存到可访问的目录在编辑器下保存到项目外。 string saveDirectory GetExportDirectory(); string fullPath Path.Combine(saveDirectory, fileName); bool success TryExportToExcel(fullPath); if (success) { Debug.Log($数据导出成功文件位于: {fullPath}); // 可以在这里触发一个UI提示 #if UNITY_EDITOR UnityEditor.EditorUtility.RevealInFinder(fullPath); #endif } else { Debug.LogWarning(数据导出失败。当前平台可能不支持直接生成Excel文件。); // 备选方案导出为CSV或JSON ExportToCsvAsFallback(saveDirectory); } } private string GetExportDirectory() { #if UNITY_EDITOR return Path.Combine(Application.dataPath, .., Exports); #elif UNITY_STANDALONE_WIN || UNITY_STANDALONE_OSX || UNITY_STANDALONE_LINUX return Path.Combine(Application.persistentDataPath, Exports); #else return Application.persistentDataPath; // 移动端等 #endif } private bool TryExportToExcel(string filePath) { // 使用条件编译确保只有支持EPPlus的平台才会编译此代码 #if UNITY_EDITOR || UNITY_STANDALONE try { var collector RuntimeDataCollector.Instance; if (collector null) { Debug.LogError(数据收集器未找到。); return false; } Directory.CreateDirectory(Path.GetDirectoryName(filePath)); using (ExcelPackage excelPackage new ExcelPackage()) { foreach (var kvp in collector.GetAllTables()) // 假设在收集器中添加了GetAllTables方法 { DataTable table kvp.Value; ExcelWorksheet worksheet string.IsNullOrEmpty(table.TableName) ? excelPackage.Workbook.Worksheets.Add($Sheet{excelPackage.Workbook.Worksheets.Count 1}) : excelPackage.Workbook.Worksheets.Add(table.TableName); // 写入表头 for (int col 0; col table.Headers.Count; col) { worksheet.Cells[1, col 1].Value table.Headers[col]; worksheet.Cells[1, col 1].Style.Font.Bold true; } // 写入数据行 for (int row 0; row table.Rows.Count; row) { DataRow dataRow table.Rows[row]; for (int col 0; col dataRow.Values.Count; col) { // 注意Excel行号从1开始且第一行是表头 worksheet.Cells[row 2, col 1].Value dataRow.Values[col]; } } // 自动调整列宽可选 worksheet.Cells[worksheet.Dimension.Address].AutoFitColumns(); } FileInfo excelFile new FileInfo(filePath); excelPackage.SaveAs(excelFile); return true; } } catch (System.Exception e) { Debug.LogError($导出Excel时发生错误: {e.Message}\n{e.StackTrace}); return false; } #else // 对于不支持EPPlus的平台如移动端直接返回false Debug.LogWarning(当前构建平台不支持直接生成Excel文件。); return false; #endif } private void ExportToCsvAsFallback(string directory) { // 实现将DataTable导出为CSV文件的逻辑作为备选。 // CSV文件同样可以用Excel打开且兼容性极好。 Debug.Log(已启用备选方案导出为CSV格式。); // ... CSV导出实现代码 } }这个RuntimeDataExporter类是连接游戏运行时与Excel生成器的桥梁。TryExportToExcel方法被#if UNITY_EDITOR || UNITY_STANDALONE预处理器指令包裹这意味着在构建移动端应用时这部分代码根本不会被编译进去避免了运行时错误。在编辑器或PC独立游戏运行时则可以正常调用EPPlus生成.xlsx文件。GetExportDirectory方法根据平台选择合理的输出路径在编辑器下输出到项目外的Exports文件夹避免污染Assets在PC版游戏中则输出到持久化数据路径。5.3 为移动端提供替代导出方案对于移动端等无法使用EPPlus的平台我们必须提供一个友好的替代方案。CSV是最佳选择。private void ExportToCsvAsFallback(string directory) { var collector RuntimeDataCollector.Instance; if (collector null) return; foreach (var kvp in collector.GetAllTables()) { DataTable table kvp.Value; if (table.Rows.Count 0) continue; string csvFilePath Path.Combine(directory, ${table.TableName}_{System.DateTime.Now:yyyyMMdd_HHmmss}.csv); using (StreamWriter sw new StreamWriter(csvFilePath, false, System.Text.Encoding.UTF8)) { // 写入表头 sw.WriteLine(string.Join(,, table.Headers)); // 写入数据行 foreach (DataRow row in table.Rows) { // 处理CSV特殊字符包含逗号、换行符、引号的字段需要用双引号括起来并且内部的双引号要转义为两个双引号。 Liststring escapedValues new Liststring(); foreach (object val in row.Values) { string str val?.ToString() ?? ; if (str.Contains(,) || str.Contains(\) || str.Contains(\n) || str.Contains(\r)) { str \ str.Replace(\, \\) \; } escapedValues.Add(str); } sw.WriteLine(string.Join(,, escapedValues)); } } Debug.Log($CSV文件已生成: {csvFilePath}); } }这个CSV导出器虽然简单但处理了字段转义生成的.csv文件可以直接用Excel打开实现了数据的可读性。你可以在游戏内提供一个“分享”或“发送邮件”的按钮将这个CSV文件作为附件发送给用户自己或者上传到服务器。6. 性能优化与内存管理实战要点在Unity中处理Excel文件尤其是当数据量较大时例如数万行性能和不规范操作导致的内存泄漏是需要警惕的问题。以下是我在实际项目中总结的几个关键点。6.1 流式处理与大文件分块读取EPPlus在加载Excel文件时默认会将整个工作簿读入内存。对于几十MB甚至上百MB的巨型Excel文件这可能导致Unity编辑器卡顿甚至崩溃。EPPlus提供了ExcelPackage.Load方法的一个重载支持使用FileStream并设置LoadOptions但更根本的优化策略是“分块读取”或“流式读取”。对于导入操作如果文件非常大可以考虑与策划约定将大表拆分为多个按功能或范围划分的小文件。这是最有效的办法。如果必须处理大文件可以在导入工具中增加“预览模式”或“分批导入”选项。例如先读取前1000行生成配置映射确认无误后再进行全量导入。全量导入时可以分批次读取例如每次处理5000行每处理完一批就调用Resources.UnloadUnusedAssets()和System.GC.Collect()谨慎使用来及时释放内存并更新进度条避免界面假死。// 伪代码分批读取示例 int batchSize 5000; int totalRows worksheet.Dimension.Rows; for (int startRow dataStartRow; startRow totalRows; startRow batchSize) { int endRow Math.Min(startRow batchSize - 1, totalRows); // 读取从startRow到endRow的数据并处理 ProcessRowRange(worksheet, startRow, endRow, columnMappings); // 更新UI进度 EditorUtility.DisplayProgressBar(导入中, $正在处理行 {startRow}-{endRow} / {totalRows}, (float)startRow / totalRows); // 强制垃圾回收仅在编辑器工具中可考虑使用运行时慎用 System.GC.Collect(); System.GC.WaitForPendingFinalizers(); Resources.UnloadUnusedAssets(); } EditorUtility.ClearProgressBar();6.2 至关重要的Dispose与Using语句EPPlus的ExcelPackage和ExcelWorksheet对象可能持有非托管资源如文件流、压缩流。必须确保在使用完毕后正确释放它们。最可靠、最推荐的方式就是使用using语句块。// 正确做法使用using确保资源释放 using (ExcelPackage excelPackage new ExcelPackage(new FileInfo(filePath))) { ExcelWorksheet worksheet excelPackage.Workbook.Worksheets[0]; // ... 操作worksheet } // 离开此代码块时excelPackage.Dispose()会被自动调用所有资源得到释放。 // 错误做法手动管理容易遗忘 ExcelPackage excelPackage new ExcelPackage(new FileInfo(filePath)); // ... 如果中间发生异常Dispose可能不会被调用导致资源泄漏。 // excelPackage.Dispose(); // 需要手动调用且要放在finally块中。在编辑器工具中如果不使用using且没有正确Dispose反复执行导入操作可能会导致内存占用持续增长最终引发OutOfMemoryException。将ExcelPackage和用于读取文件的FileStream都包裹在using中是必须养成的编码习惯。6.3 缓存与数据复用策略在游戏运行时我们导出的数据通常不会特别巨大但也要注意效率。RuntimeDataCollector在记录数据时使用的是Listobject来存储值。对于值类型如int, float, bool这会引发装箱Boxing操作产生额外的内存分配和GC压力。对于高性能要求的场景如每帧记录大量事件可以考虑进行优化使用特定类型的DataRow为不同的数据表创建强类型的行类如GameSessionRow内部使用int score; float playTime;等字段避免装箱。对象池如果DataRow需要频繁创建和销毁可以实现一个简单的对象池来复用对象减少GC次数。延迟写入/批量写入不要每次事件都直接调用AddRow。可以先将数据缓存在一个临时的、结构更简单的缓冲区如StringBuilder或数组定期如每秒或当缓冲区满时再一次性封装成DataRow添加到DataTable中。这能减少对复杂集合结构的频繁操作。7. 常见问题排查与实战技巧实录即使按照教程一步步操作在实际集成中你仍可能遇到一些棘手的问题。下面是我和同事们踩过的一些坑以及解决方案希望能帮你节省大量调试时间。7.1 编译错误“类型或命名空间‘OfficeOpenXml’不存在”这是最常见的问题意味着Unity没有找到EPPlus的DLL。检查DLL位置确认EPPlus.dll是否放在了Assets/Plugins或Assets/Plugins/Editor目录下。Assets/Editor目录下的脚本不能直接引用Plugins根目录的DLL但可以引用Plugins/Editor下的。对于同时被编辑器脚本和运行时脚本引用的DLL放在Plugins根目录是标准做法。检查DLL兼容性在文件管理器中对EPPlus.dll右键-属性查看详细信息。确保其产品版本与下载的.NET Standard 2.0版本一致。尝试重新从官方GitHub Release页面下载。重启Unity/刷新项目有时Unity的编译缓存会出问题。尝试在Unity中Assets - Reimport All或者完全关闭Unity并删除项目目录下的Library和obj文件夹后重新打开。检查API兼容级别在Player Settings - Other Settings - Configuration中确保Api Compatibility Level设置为.NET Standard 2.0或.NET Framework而不是.NET Micro。EPPlus需要较新的API支持。7.2 运行时错误在构建后尤其是IL2CPP报错在编辑器下运行正常但构建到PC、Android或iOS后崩溃并可能伴随DllNotFoundException或InvalidOperationException。根本原因你很可能在运行时脚本非Editor目录下中直接使用了EPPlus代码并且没有用条件编译#if UNITY_EDITOR将其隔离。IL2CPP编译器可能会尝试编译这些代码但由于缺少依赖或平台不支持而失败。解决方案严格遵循本教程的设计将所有直接调用EPPlus API的代码放在Editor目录下的脚本中或者用#if UNITY_EDITOR || UNITY_STANDALONE预处理器指令包裹。确保你的RuntimeDataExporter类中的TryExportToExcel方法正确使用了条件编译。检查依赖DLL如果EPPlus依赖其他DLL如System.Drawing.Common确保这些DLL也被放置在Plugins目录下并且其平台兼容性设置正确在Unity Inspector中确保其目标平台包含你正在构建的平台。7.3 生成的Excel文件用Excel打开时报错或乱码文件损坏确保在保存ExcelPackage时using块正常退出文件流被正确关闭。避免在保存过程中发生异常。中文或特殊字符乱码EPPlus默认使用UTF-8编码现代Excel对此支持良好。如果出现乱码检查数据源本身。在写入字符串时确保其编码正确。对于CSV备用方案在StreamWriter中显式指定Encoding.UTF8并带BOM头new UTF8Encoding(true)可以最大程度保证兼容性。公式不计算通过EPPlus设置的公式在Excel中打开时默认会显示公式本身而非计算结果。需要确保worksheet.Cells[].Formula设置正确并且Excel的自动计算是开启的。你也可以在保存前强制计算一次excelPackage.Workbook.Calculate()这样保存的就是计算结果。7.4 在Mac版Unity编辑器下的注意事项路径分隔符C#的Path.Combine方法会处理不同平台的路径分隔符问题但手动拼接字符串时请使用Path.Combine避免使用硬编码的\或/。文件访问权限如果你将Excel文件保存在Application.dataPath即Assets文件夹内Unity可能会尝试将其作为资源导入导致文件被锁定或修改。最佳实践如教程所示将导入的源Excel文件和导出的目标文件都放在Assets文件夹之外例如项目根目录的Config或Exports文件夹。EPPlus在macOS上的表现EPPlus是纯托管代码库在macOS的Unity编辑器下运行通常没有问题。但如果遇到问题可以尝试使用EPPlus的ExcelPackage.LicenseContext属性设置为NonCommercial如果你在非商业项目中使用或Commercial这有时能解决一些在非Windows系统上的初始化问题。7.5 扩展技巧处理复杂单元格与样式EPPlus的功能远不止读写文本和数字。通过它你可以创建专业的Excel报表单元格样式worksheet.Cells[A1].Style.Font.Bold true;worksheet.Cells[B2].Style.Fill.PatternType OfficeOpenXml.Style.ExcelFillStyle.Solid;worksheet.Cells[B2].Style.Fill.BackgroundColor.SetColor(System.Drawing.Color.LightBlue);设置列宽行高worksheet.Column(1).Width 20;worksheet.Row(1).Height 25;合并单元格worksheet.Cells[A1:C1].Merge true;创建简单图表仅限高级版本或特定场景虽然可行但在Unity编辑器工具中动态生成图表的需求较少且会使依赖复杂化一般建议将原始数据导出后由Excel自身或其它专业工具生成图表。最后一个非常重要的心得是保持编辑器工具的鲁棒性。在你的导入工具中加入详尽的日志输出和错误处理。当策划提供的Excel表格列数不对、格式错误时工具应该给出明确、友好的错误提示如“第X行第Y列的数据‘abc’无法转换为整数”而不是让Unity控制台抛出一堆令人困惑的异常。这能极大降低非技术人员的使用门槛和你的维护成本。
1. 项目概述与核心价值在Unity3D项目开发中尤其是涉及游戏配置、关卡数据、本地化文本或者玩家数据存档时我们常常需要处理结构化数据。虽然Unity自带的ScriptableObject和JSON序列化非常方便但在很多实际工作流中策划、运营或非技术同事更习惯使用Excel来编辑和维护这些数据。因此实现Unity3D与Excel文件的动态交互就成了一个连接开发管线与内容生产环节的刚需。这个需求的核心不仅仅是“能读写”更是要“在运行时动态创建、写入并能被Excel正常打开”同时还要兼顾跨平台兼容性、性能以及避免引入复杂的依赖。网上相关的讨论很多但坑也不少。就像我最初尝试时一样兴冲冲地引入了某个看起来功能强大的第三方Excel库结果Unity直接报错提示找不到命名空间或者构建到移动平台时直接崩溃。这背后的原因在于很多为.NET Framework设计的Excel库严重依赖Windows系统组件或特定的运行时环境这与Unity基于Mono或IL2CPP的跨平台运行时天生不兼容。所以这个教程的目的就是带你绕开这些坑找到在Unity中实现Excel读写特别是动态创建与写入的可靠、实用的方案。无论你是想制作一个由Excel驱动关卡数据的独立游戏还是需要为工具链开发一个数据导出功能这篇文章都能给你一套经过验证的、可直接落地的代码和思路。2. 方案选型为什么放弃“重量级”库选择“轻量级”协议在动手写代码之前我们先来彻底搞清楚方案选型的逻辑。为什么社区里普遍不推荐直接在Unity里用类似Microsoft.Office.Interop.Excel或者Aspose.Cells这样的库这不仅仅是“能不能用”的问题更是“好不好用”、“稳不稳定”的根本性问题。2.1 剖析传统Excel库的兼容性陷阱以Microsoft.Office.Interop.Excel为例它本质上是一组COM接口的封装要求你的运行环境中必须安装有完整版本的Microsoft Excel。这在Windows PC上开发时或许能跑起来但一旦你尝试构建项目到其他平台比如iOS、Android、WebGL或者甚至是没有安装Excel的Windows PC上程序会立刻崩溃。因为它依赖的COM组件和Excel可执行文件根本不存在于目标平台。这完全违背了Unity“一次编写多平台部署”的核心优势。另一个常见选择是Aspose.Cells或EPPlus等第三方商业或开源库。这些库功能确实强大支持复杂的格式、公式、图表。但问题同样出在依赖和运行时上。许多这类库为了高性能底层使用了.NET Framework中的一些特定API如System.Drawing或者原生的互操作这些在Unity的裁剪后运行时尤其是IL2CPP中可能无法正常工作或者需要引入额外的、可能不稳定的C插件。此外它们的程序集通常较大会增加最终构建包的体积。从网络讨论中那位开发者遇到的“Unity突然丢失库引用”的错误来看这种不稳定的兼容性问题在实践中非常普遍。2.2 CSV与JSON轻量级替代方案的优劣对比于是社区的主流建议转向了更简单的文本格式CSV和JSON。CSV逗号分隔值文件本质上是纯文本用逗号或制表符分隔数据。它的最大优势是极度简单任何文本编辑器都能打开Excel也能直接导入和保存。在Unity中使用System.IO命名空间下的StreamReader和StreamWriter就能轻松读写零依赖全平台兼容。对于仅仅是存储表格数据行和列的场景CSV几乎是最佳选择。但是它的缺点也很明显它无法存储复杂的格式如单元格颜色、字体、多工作表Sheet、合并单元格或公式。数据如果包含逗号或换行符还需要额外的转义处理。JSON是另一种优秀的轻量级数据交换格式。它结构清晰嵌套灵活非常适合表示复杂的、层次化的数据比如一个角色的所有属性包含装备列表、技能树等。Unity对JSON有原生支持通过JsonUtility或第三方库如Newtonsoft.Json序列化和反序列化非常方便。然而JSON文件对于非技术背景的策划或运营人员来说直接编辑并不友好它缺乏Excel那种直观的表格视图。2.3 核心思路分离数据编辑与运行时使用基于以上分析一个健壮的、适用于生产环境的方案其核心思路应该是“编辑时用Excel运行时用中间格式”。策划/运营在熟悉的Excel中编辑数据利用其强大的格式、公式、数据验证等功能。开发管线通过一个编辑器工具Editor Script将Excel文件.xlsx或.xls在Unity编辑器中转换为游戏运行时易于加载的格式如JSON、二进制文件或直接注入到ScriptableObject中。游戏运行时Unity程序只加载处理好的JSON或二进制数据完全摆脱对Excel库的依赖。这个流程完美解决了兼容性和易用性的矛盾。我们只需要在Unity编辑器环境下解决Excel读取问题而编辑器环境是相对可控的Windows/macOS系统。对于动态“写入”Excel的需求通常也发生在这个编辑器工具环节比如将游戏内的配置或统计结果导出成一份给策划看的Excel报告。因此本教程将聚焦于实现这一流程的两个关键部分一是在Unity编辑器下可靠地读取和写入.xlsx文件二是在游戏运行时如何设计数据结构和流程来支持类似“动态创建数据表并导出”的需求。3. 实战准备选择与集成可靠的Excel操作库既然确定了主战场在编辑器下我们就可以选择一个专为.NET环境设计、不依赖Office安装、且与Unity兼容性较好的库。这里我强烈推荐EPPlus。这是一个开源从5.0开始使用Polyform Noncommercial License需注意商业用途许可且功能强大的.NET库专门用于操作Open Office XML格式即.xlsx。它不需要安装Excel纯托管代码实现在Unity的编辑器脚本中使用非常稳定。3.1 在Unity中安装EPPlusEPPlus通常以DLL的形式提供。最稳妥的获取方式是通过其GitHub仓库发布页下载编译好的.NET Standard 2.0版本DLL这个版本与Unity的兼容性最好。下载DLL访问EPPlus的GitHub仓库在Releases页面找到并下载EPPlus.xxx.zip文件。解压后找到名为EPPlus.dll的核心文件。导入Unity在你的Unity项目Assets目录下创建一个名为Plugins的文件夹如果不存在。将EPPlus.dll复制到Assets/Plugins目录下。Unity会自动识别并导入它。处理依赖EPPlus 5.0版本可能依赖System.Drawing.Common。对于Unity 2020及以上版本基于.NET Standard 2.1或.NET Framework 4.x这个依赖通常已包含。如果遇到缺失System.Drawing相关错误你可能需要从NuGet或其他来源获取System.Drawing.Common.dll同样放入Plugins文件夹。注意务必确保你下载的是适用于.NET Standard 2.0的版本。直接使用针对完整.NET Framework的DLL可能在Unity中引发运行时错误。将DLL放入Plugins文件夹是关键这能确保Unity在编译编辑器脚本时正确引用它。3.2 验证安装与基础读写测试创建一个新的C#脚本命名为ExcelEditorTool.cs将其放在Assets/Editor目录下确保它只在编辑器环境下运行。using UnityEngine; using UnityEditor; using System.IO; // 引入EPPlus命名空间 using OfficeOpenXml; public class ExcelEditorTool : EditorWindow { [MenuItem(Tools/Excel/Test EPPlus)] static void TestEPPlusConnection() { // 创建一个全新的Excel包在内存中 using (ExcelPackage excelPackage new ExcelPackage()) { // 添加一个工作表 ExcelWorksheet worksheet excelPackage.Workbook.Worksheets.Add(TestSheet); // 向单元格写入数据 worksheet.Cells[1, 1].Value Hello; worksheet.Cells[1, 2].Value Unity; worksheet.Cells[2, 1].Value 42; worksheet.Cells[2, 2].Formula A2*2; // 甚至支持公式 // 设置单元格样式 worksheet.Cells[1, 1, 1, 2].Style.Font.Bold true; worksheet.Cells[2, 1].Style.Numberformat.Format 0.00; // 定义保存路径在项目Assets目录外避免Unity自动导入 string savePath Path.Combine(Application.dataPath, .., TestOutput.xlsx); // 将Excel包保存为文件 FileInfo excelFile new FileInfo(savePath); excelPackage.SaveAs(excelFile); Debug.Log($测试Excel文件已生成: {savePath}); EditorUtility.RevealInFinder(savePath); // 在文件管理器中打开所在文件夹 } } }点击Unity编辑器菜单栏的Tools/Excel/Test EPPlus。如果一切顺利你会在项目上一级目录看到生成的TestOutput.xlsx文件用Excel打开它你会看到“Hello”和“Unity”两个加粗的单元格以及一个数字和公式。这个测试成功意味着EPPlus已经在你的Unity编辑器中正常工作为我们后续的所有操作打下了基础。这个简单的测试也展示了EPPlus的核心对象模型ExcelPackage代表整个工作簿ExcelWorksheet代表单个工作表Cells[row, col]用于访问和操作单元格。4. 核心模块一编辑器工具——从Excel到游戏数据这是自动化管线的核心。我们将创建一个功能完整的编辑器窗口用于将策划配置的Excel表格一键转换为Unity游戏可用的数据资产ScriptableObject或JSON文件。4.1 设计可配置的转换映射规则策划的Excel表格结构多样我们需要一个灵活的方式来定义“Excel中的哪一列对应游戏数据类的哪个属性”。为此我们创建一个配置类ExcelImportConfig。using UnityEngine; using System; [CreateAssetMenu(fileName NewExcelConfig.asset, menuName Game/Excel Import Config)] public class ExcelImportConfig : ScriptableObject { public string excelFilePath; // Excel文件的相对路径如Assets/Config/Levels.xlsx public string worksheetName Sheet1; // 要读取的工作表名 public bool hasHeaderRow true; // 第一行是否为标题行 public int dataStartRow 2; // 数据开始的行号如果标题行是第1行这里就是2 // 列映射Excel列索引1-based - 数据类属性名 public ColumnMapping[] columnMappings; [Serializable] public class ColumnMapping { public int excelColumnIndex; // Excel中的列号A1, B2... public string dataFieldName; // 对应C#数据类中的字段名 public string dataFieldType; // 字段类型如int, float, string, bool } // 输出的数据容器ScriptableObject的预制类型 public ScriptableObject outputDataContainerTemplate; // 或输出为JSON文件的路径 public string jsonOutputPath; }这个配置资产允许策划或开发者通过Unity Inspector界面直观地设置转换规则。例如一个关卡配置表第1列ID映射到LevelData类的id字段int类型第2列关卡名映射到name字段string类型。4.2 实现通用的Excel解析与转换引擎接下来我们实现一个强大的ExcelImporter类它利用EPPlus读取Excel并根据上述配置进行转换。using OfficeOpenXml; using System; using System.Collections.Generic; using System.IO; using UnityEngine; public static class ExcelImporter { public static ListT ImportFromExcelT(ExcelImportConfig config) where T : new() { ListT dataList new ListT(); FileInfo excelFile new FileInfo(Path.Combine(Application.dataPath, .., config.excelFilePath)); if (!excelFile.Exists) { Debug.LogError($Excel文件不存在: {excelFile.FullName}); return dataList; } using (ExcelPackage excelPackage new ExcelPackage(excelFile)) { ExcelWorksheet worksheet excelPackage.Workbook.Worksheets[config.worksheetName]; if (worksheet null) { Debug.LogError($在工作簿中未找到工作表: {config.worksheetName}); return dataList; } int startRow config.hasHeaderRow ? config.dataStartRow : 1; int row startRow; // 循环读取每一行直到遇到第一个所有映射列都为空的单元格视为数据结束 while (true) { bool rowHasData false; T dataItem new T(); var dataType typeof(T); foreach (var mapping in config.columnMappings) { int col mapping.excelColumnIndex; var cell worksheet.Cells[row, col]; object cellValue cell.Value; if (cellValue ! null !string.IsNullOrWhiteSpace(cellValue.ToString())) { rowHasData true; } // 将单元格值转换为目标类型并赋值 try { var field dataType.GetField(mapping.dataFieldName); if (field ! null) { object convertedValue ConvertCellValue(cellValue, mapping.dataFieldType); field.SetValue(dataItem, convertedValue); } } catch (Exception e) { Debug.LogWarning($第{row}行第{col}列映射到{mapping.dataFieldName}数据转换失败: {e.Message}); } } if (!rowHasData) { break; // 遇到空行停止读取 } dataList.Add(dataItem); row; } } Debug.Log($从 {config.excelFilePath} 成功导入 {dataList.Count} 条数据到类型 {typeof(T).Name}。); return dataList; } private static object ConvertCellValue(object cellValue, string targetType) { if (cellValue null) return GetDefaultValue(targetType); string stringValue cellValue.ToString(); switch (targetType.ToLower()) { case int: if (int.TryParse(stringValue, out int intResult)) return intResult; return 0; case float: if (float.TryParse(stringValue, out float floatResult)) return floatResult; return 0f; case bool: // 支持1/0, true/false, 是/否等多种布尔表示 if (int.TryParse(stringValue, out int intBool)) return intBool ! 0; if (bool.TryParse(stringValue, out bool boolResult)) return boolResult; return stringValue.Equals(是, StringComparison.OrdinalIgnoreCase); case string: default: return stringValue; } } private static object GetDefaultValue(string type) { switch (type.ToLower()) { case int: return 0; case float: return 0f; case bool: return false; default: return null; } } }这个导入器的核心是一个泛型方法它可以自动将Excel行映射到任何你定义的C#数据类通过where T : new()约束。ConvertCellValue方法处理了类型转换的细节增强了鲁棒性。在实际项目中你可能还需要处理更复杂的类型如枚举、数组可以用特定分隔符如分号存储在一格内、甚至对其它数据行的引用。4.3 构建易用的编辑器界面与自动化流程最后我们将配置和导入逻辑整合到一个用户友好的编辑器窗口中。using UnityEditor; using UnityEngine; using System.Collections.Generic; using System.IO; public class ExcelImportWindow : EditorWindow { private ExcelImportConfig currentConfig; private Vector2 scrollPos; private string statusMessage ; private MessageType statusType MessageType.None; [MenuItem(Tools/Excel/Import Window)] static void Init() { GetWindowExcelImportWindow(Excel导入工具).Show(); } void OnGUI() { scrollPos EditorGUILayout.BeginScrollView(scrollPos); // 1. 选择或创建配置 EditorGUILayout.LabelField(配置设置, EditorStyles.boldLabel); currentConfig (ExcelImportConfig)EditorGUILayout.ObjectField(导入配置, currentConfig, typeof(ExcelImportConfig), false); if (currentConfig null) { if (GUILayout.Button(创建新配置)) { string path EditorUtility.SaveFilePanelInProject(保存配置, ExcelImportConfig, asset, 请选择保存位置); if (!string.IsNullOrEmpty(path)) { currentConfig CreateInstanceExcelImportConfig(); AssetDatabase.CreateAsset(currentConfig, path); AssetDatabase.Refresh(); } } EditorGUILayout.EndScrollView(); return; } // 2. 绘制配置详情 EditorGUI.BeginChangeCheck(); SerializedObject so new SerializedObject(currentConfig); SerializedProperty sp so.FindProperty(excelFilePath); EditorGUILayout.PropertyField(sp); // ... 绘制其他属性如worksheetName, hasHeaderRow等 // 动态绘制ColumnMapping数组 sp so.FindProperty(columnMappings); EditorGUILayout.PropertyField(sp, true); if (EditorGUI.EndChangeCheck()) { so.ApplyModifiedProperties(); EditorUtility.SetDirty(currentConfig); } EditorGUILayout.Space(20); // 3. 操作按钮 EditorGUILayout.LabelField(操作, EditorStyles.boldLabel); if (GUILayout.Button(预览Excel前5行, GUILayout.Height(30))) { PreviewExcelData(); } if (GUILayout.Button(执行导入 (生成ScriptableObject), GUILayout.Height(40))) { ImportToScriptableObject(); } if (GUILayout.Button(执行导入 (生成JSON文件), GUILayout.Height(40))) { ImportToJson(); } // 4. 状态显示 if (!string.IsNullOrEmpty(statusMessage)) { EditorGUILayout.HelpBox(statusMessage, statusType); } EditorGUILayout.EndScrollView(); } void PreviewExcelData() { // 使用EPPlus读取文件获取指定工作表的前几行数据并在窗口中显示。 // 这能帮助用户确认列映射是否正确。 statusMessage 预览功能待实现。请先手动用Excel打开文件核对列结构。; statusType MessageType.Info; } void ImportToScriptableObject() { if (currentConfig.outputDataContainerTemplate null) { statusMessage 错误请先配置‘输出数据容器模板’。; statusType MessageType.Error; return; } // 这里假设模板是一个包含ListT的ScriptableObject。 // 1. 使用ExcelImporter.ImportFromExcelT导入数据列表。 // 2. 实例化模板将数据列表赋值给它。 // 3. 使用AssetDatabase.CreateAsset保存为新的.asset文件。 statusMessage 导入成功已生成ScriptableObject数据资产。; statusType MessageType.Info; } void ImportToJson() { if (string.IsNullOrEmpty(currentConfig.jsonOutputPath)) { statusMessage 错误请先配置‘JSON输出路径’。; statusType MessageType.Error; return; } // 1. 使用ExcelImporter.ImportFromExcelT导入数据列表。 // 2. 使用JsonUtility.ToJson将列表序列化为JSON字符串。 // 3. 使用File.WriteAllText写入到配置的路径。 statusMessage 导入成功已生成JSON数据文件。; statusType MessageType.Info; } }这个窗口提供了完整的GUI加载配置、编辑映射规则、执行导入。PreviewExcelData函数可以进一步扩展用DataGrid之类的控件显示读取的原始数据让映射配置过程更加直观。通过这样的工具策划只需维护Excel文件开发者一键即可将其同步到游戏项目中极大地提升了协作效率和数据一致性。5. 核心模块二运行时逻辑——动态数据收集与导出虽然游戏运行时不应依赖Excel库但“动态创建数据并导出为Excel”的需求是真实存在的例如导出玩家行为日志、生成关卡编辑器的数据模板、输出游戏内经济系统统计报表等。这里的“动态创建”指的是在游戏运行过程中或通过一个特殊的“导出模式”程序收集数据并在编辑器环境或PC独立构建中调用EPPlus生成Excel文件。5.1 设计运行时数据收集器首先我们需要一个与游戏逻辑解耦的数据收集系统。它不关心数据最终是写成Excel、JSON还是上传到服务器只负责按照定义好的格式收集数据。using System; using System.Collections.Generic; // 定义一个通用的数据行 public class DataRow { public Listobject Values { get; private set; } new Listobject(); public void AddValue(object value) { Values.Add(value); } } // 定义一个数据表包含列头和多行数据 public class DataTable { public string TableName { get; set; } public Liststring Headers { get; private set; } new Liststring(); public ListDataRow Rows { get; private set; } new ListDataRow(); public DataRow CreateRow() { DataRow row new DataRow(); Rows.Add(row); return row; } // 添加一行数据参数顺序对应列顺序 public void AddRow(params object[] values) { DataRow row CreateRow(); foreach (var v in values) { row.AddValue(v); } } } // 运行时数据收集管理器单例示例 public class RuntimeDataCollector : MonoBehaviour { private static RuntimeDataCollector _instance; public static RuntimeDataCollector Instance _instance; private Dictionarystring, DataTable _tables new Dictionarystring, DataTable(); void Awake() { if (_instance ! null _instance ! this) { Destroy(gameObject); return; } _instance this; DontDestroyOnLoad(gameObject); } public DataTable GetOrCreateTable(string tableName) { if (!_tables.ContainsKey(tableName)) { _tables[tableName] new DataTable { TableName tableName }; } return _tables[tableName]; } // 示例收集玩家每局游戏数据 public void RecordGameSession(string playerId, int score, float playTime, string levelName) { var table GetOrCreateTable(GameSessions); if (table.Headers.Count 0) { table.Headers.AddRange(new[] { 时间戳, 玩家ID, 得分, 游戏时长(秒), 关卡名 }); } table.AddRow(DateTime.Now.ToString(yyyy-MM-dd HH:mm:ss), playerId, score, playTime, levelName); } public void ClearTable(string tableName) { if (_tables.ContainsKey(tableName)) { _tables[tableName].Rows.Clear(); } } public void ClearAll() { _tables.Clear(); } }这个收集器非常轻量只在内存中维护数据。游戏逻辑在任何地方都可以调用RuntimeDataCollector.Instance.RecordGameSession(...)来记录数据。所有数据按表组织便于后续按不同主题导出。5.2 实现跨平台的导出触发机制接下来是关键如何安全地触发Excel导出由于EPPlus不能在iOS/Android等平台的运行时使用我们必须通过条件编译将导出逻辑隔离。using UnityEngine; using System.IO; #if UNITY_EDITOR using OfficeOpenXml; #endif public class RuntimeDataExporter : MonoBehaviour { // 提供给游戏内UI按钮调用的方法 public void ExportAllDataToExcel() { string fileName $GameData_Export_{System.DateTime.Now:yyyyMMdd_HHmmss}.xlsx; // 在PC上保存到可访问的目录在编辑器下保存到项目外。 string saveDirectory GetExportDirectory(); string fullPath Path.Combine(saveDirectory, fileName); bool success TryExportToExcel(fullPath); if (success) { Debug.Log($数据导出成功文件位于: {fullPath}); // 可以在这里触发一个UI提示 #if UNITY_EDITOR UnityEditor.EditorUtility.RevealInFinder(fullPath); #endif } else { Debug.LogWarning(数据导出失败。当前平台可能不支持直接生成Excel文件。); // 备选方案导出为CSV或JSON ExportToCsvAsFallback(saveDirectory); } } private string GetExportDirectory() { #if UNITY_EDITOR return Path.Combine(Application.dataPath, .., Exports); #elif UNITY_STANDALONE_WIN || UNITY_STANDALONE_OSX || UNITY_STANDALONE_LINUX return Path.Combine(Application.persistentDataPath, Exports); #else return Application.persistentDataPath; // 移动端等 #endif } private bool TryExportToExcel(string filePath) { // 使用条件编译确保只有支持EPPlus的平台才会编译此代码 #if UNITY_EDITOR || UNITY_STANDALONE try { var collector RuntimeDataCollector.Instance; if (collector null) { Debug.LogError(数据收集器未找到。); return false; } Directory.CreateDirectory(Path.GetDirectoryName(filePath)); using (ExcelPackage excelPackage new ExcelPackage()) { foreach (var kvp in collector.GetAllTables()) // 假设在收集器中添加了GetAllTables方法 { DataTable table kvp.Value; ExcelWorksheet worksheet string.IsNullOrEmpty(table.TableName) ? excelPackage.Workbook.Worksheets.Add($Sheet{excelPackage.Workbook.Worksheets.Count 1}) : excelPackage.Workbook.Worksheets.Add(table.TableName); // 写入表头 for (int col 0; col table.Headers.Count; col) { worksheet.Cells[1, col 1].Value table.Headers[col]; worksheet.Cells[1, col 1].Style.Font.Bold true; } // 写入数据行 for (int row 0; row table.Rows.Count; row) { DataRow dataRow table.Rows[row]; for (int col 0; col dataRow.Values.Count; col) { // 注意Excel行号从1开始且第一行是表头 worksheet.Cells[row 2, col 1].Value dataRow.Values[col]; } } // 自动调整列宽可选 worksheet.Cells[worksheet.Dimension.Address].AutoFitColumns(); } FileInfo excelFile new FileInfo(filePath); excelPackage.SaveAs(excelFile); return true; } } catch (System.Exception e) { Debug.LogError($导出Excel时发生错误: {e.Message}\n{e.StackTrace}); return false; } #else // 对于不支持EPPlus的平台如移动端直接返回false Debug.LogWarning(当前构建平台不支持直接生成Excel文件。); return false; #endif } private void ExportToCsvAsFallback(string directory) { // 实现将DataTable导出为CSV文件的逻辑作为备选。 // CSV文件同样可以用Excel打开且兼容性极好。 Debug.Log(已启用备选方案导出为CSV格式。); // ... CSV导出实现代码 } }这个RuntimeDataExporter类是连接游戏运行时与Excel生成器的桥梁。TryExportToExcel方法被#if UNITY_EDITOR || UNITY_STANDALONE预处理器指令包裹这意味着在构建移动端应用时这部分代码根本不会被编译进去避免了运行时错误。在编辑器或PC独立游戏运行时则可以正常调用EPPlus生成.xlsx文件。GetExportDirectory方法根据平台选择合理的输出路径在编辑器下输出到项目外的Exports文件夹避免污染Assets在PC版游戏中则输出到持久化数据路径。5.3 为移动端提供替代导出方案对于移动端等无法使用EPPlus的平台我们必须提供一个友好的替代方案。CSV是最佳选择。private void ExportToCsvAsFallback(string directory) { var collector RuntimeDataCollector.Instance; if (collector null) return; foreach (var kvp in collector.GetAllTables()) { DataTable table kvp.Value; if (table.Rows.Count 0) continue; string csvFilePath Path.Combine(directory, ${table.TableName}_{System.DateTime.Now:yyyyMMdd_HHmmss}.csv); using (StreamWriter sw new StreamWriter(csvFilePath, false, System.Text.Encoding.UTF8)) { // 写入表头 sw.WriteLine(string.Join(,, table.Headers)); // 写入数据行 foreach (DataRow row in table.Rows) { // 处理CSV特殊字符包含逗号、换行符、引号的字段需要用双引号括起来并且内部的双引号要转义为两个双引号。 Liststring escapedValues new Liststring(); foreach (object val in row.Values) { string str val?.ToString() ?? ; if (str.Contains(,) || str.Contains(\) || str.Contains(\n) || str.Contains(\r)) { str \ str.Replace(\, \\) \; } escapedValues.Add(str); } sw.WriteLine(string.Join(,, escapedValues)); } } Debug.Log($CSV文件已生成: {csvFilePath}); } }这个CSV导出器虽然简单但处理了字段转义生成的.csv文件可以直接用Excel打开实现了数据的可读性。你可以在游戏内提供一个“分享”或“发送邮件”的按钮将这个CSV文件作为附件发送给用户自己或者上传到服务器。6. 性能优化与内存管理实战要点在Unity中处理Excel文件尤其是当数据量较大时例如数万行性能和不规范操作导致的内存泄漏是需要警惕的问题。以下是我在实际项目中总结的几个关键点。6.1 流式处理与大文件分块读取EPPlus在加载Excel文件时默认会将整个工作簿读入内存。对于几十MB甚至上百MB的巨型Excel文件这可能导致Unity编辑器卡顿甚至崩溃。EPPlus提供了ExcelPackage.Load方法的一个重载支持使用FileStream并设置LoadOptions但更根本的优化策略是“分块读取”或“流式读取”。对于导入操作如果文件非常大可以考虑与策划约定将大表拆分为多个按功能或范围划分的小文件。这是最有效的办法。如果必须处理大文件可以在导入工具中增加“预览模式”或“分批导入”选项。例如先读取前1000行生成配置映射确认无误后再进行全量导入。全量导入时可以分批次读取例如每次处理5000行每处理完一批就调用Resources.UnloadUnusedAssets()和System.GC.Collect()谨慎使用来及时释放内存并更新进度条避免界面假死。// 伪代码分批读取示例 int batchSize 5000; int totalRows worksheet.Dimension.Rows; for (int startRow dataStartRow; startRow totalRows; startRow batchSize) { int endRow Math.Min(startRow batchSize - 1, totalRows); // 读取从startRow到endRow的数据并处理 ProcessRowRange(worksheet, startRow, endRow, columnMappings); // 更新UI进度 EditorUtility.DisplayProgressBar(导入中, $正在处理行 {startRow}-{endRow} / {totalRows}, (float)startRow / totalRows); // 强制垃圾回收仅在编辑器工具中可考虑使用运行时慎用 System.GC.Collect(); System.GC.WaitForPendingFinalizers(); Resources.UnloadUnusedAssets(); } EditorUtility.ClearProgressBar();6.2 至关重要的Dispose与Using语句EPPlus的ExcelPackage和ExcelWorksheet对象可能持有非托管资源如文件流、压缩流。必须确保在使用完毕后正确释放它们。最可靠、最推荐的方式就是使用using语句块。// 正确做法使用using确保资源释放 using (ExcelPackage excelPackage new ExcelPackage(new FileInfo(filePath))) { ExcelWorksheet worksheet excelPackage.Workbook.Worksheets[0]; // ... 操作worksheet } // 离开此代码块时excelPackage.Dispose()会被自动调用所有资源得到释放。 // 错误做法手动管理容易遗忘 ExcelPackage excelPackage new ExcelPackage(new FileInfo(filePath)); // ... 如果中间发生异常Dispose可能不会被调用导致资源泄漏。 // excelPackage.Dispose(); // 需要手动调用且要放在finally块中。在编辑器工具中如果不使用using且没有正确Dispose反复执行导入操作可能会导致内存占用持续增长最终引发OutOfMemoryException。将ExcelPackage和用于读取文件的FileStream都包裹在using中是必须养成的编码习惯。6.3 缓存与数据复用策略在游戏运行时我们导出的数据通常不会特别巨大但也要注意效率。RuntimeDataCollector在记录数据时使用的是Listobject来存储值。对于值类型如int, float, bool这会引发装箱Boxing操作产生额外的内存分配和GC压力。对于高性能要求的场景如每帧记录大量事件可以考虑进行优化使用特定类型的DataRow为不同的数据表创建强类型的行类如GameSessionRow内部使用int score; float playTime;等字段避免装箱。对象池如果DataRow需要频繁创建和销毁可以实现一个简单的对象池来复用对象减少GC次数。延迟写入/批量写入不要每次事件都直接调用AddRow。可以先将数据缓存在一个临时的、结构更简单的缓冲区如StringBuilder或数组定期如每秒或当缓冲区满时再一次性封装成DataRow添加到DataTable中。这能减少对复杂集合结构的频繁操作。7. 常见问题排查与实战技巧实录即使按照教程一步步操作在实际集成中你仍可能遇到一些棘手的问题。下面是我和同事们踩过的一些坑以及解决方案希望能帮你节省大量调试时间。7.1 编译错误“类型或命名空间‘OfficeOpenXml’不存在”这是最常见的问题意味着Unity没有找到EPPlus的DLL。检查DLL位置确认EPPlus.dll是否放在了Assets/Plugins或Assets/Plugins/Editor目录下。Assets/Editor目录下的脚本不能直接引用Plugins根目录的DLL但可以引用Plugins/Editor下的。对于同时被编辑器脚本和运行时脚本引用的DLL放在Plugins根目录是标准做法。检查DLL兼容性在文件管理器中对EPPlus.dll右键-属性查看详细信息。确保其产品版本与下载的.NET Standard 2.0版本一致。尝试重新从官方GitHub Release页面下载。重启Unity/刷新项目有时Unity的编译缓存会出问题。尝试在Unity中Assets - Reimport All或者完全关闭Unity并删除项目目录下的Library和obj文件夹后重新打开。检查API兼容级别在Player Settings - Other Settings - Configuration中确保Api Compatibility Level设置为.NET Standard 2.0或.NET Framework而不是.NET Micro。EPPlus需要较新的API支持。7.2 运行时错误在构建后尤其是IL2CPP报错在编辑器下运行正常但构建到PC、Android或iOS后崩溃并可能伴随DllNotFoundException或InvalidOperationException。根本原因你很可能在运行时脚本非Editor目录下中直接使用了EPPlus代码并且没有用条件编译#if UNITY_EDITOR将其隔离。IL2CPP编译器可能会尝试编译这些代码但由于缺少依赖或平台不支持而失败。解决方案严格遵循本教程的设计将所有直接调用EPPlus API的代码放在Editor目录下的脚本中或者用#if UNITY_EDITOR || UNITY_STANDALONE预处理器指令包裹。确保你的RuntimeDataExporter类中的TryExportToExcel方法正确使用了条件编译。检查依赖DLL如果EPPlus依赖其他DLL如System.Drawing.Common确保这些DLL也被放置在Plugins目录下并且其平台兼容性设置正确在Unity Inspector中确保其目标平台包含你正在构建的平台。7.3 生成的Excel文件用Excel打开时报错或乱码文件损坏确保在保存ExcelPackage时using块正常退出文件流被正确关闭。避免在保存过程中发生异常。中文或特殊字符乱码EPPlus默认使用UTF-8编码现代Excel对此支持良好。如果出现乱码检查数据源本身。在写入字符串时确保其编码正确。对于CSV备用方案在StreamWriter中显式指定Encoding.UTF8并带BOM头new UTF8Encoding(true)可以最大程度保证兼容性。公式不计算通过EPPlus设置的公式在Excel中打开时默认会显示公式本身而非计算结果。需要确保worksheet.Cells[].Formula设置正确并且Excel的自动计算是开启的。你也可以在保存前强制计算一次excelPackage.Workbook.Calculate()这样保存的就是计算结果。7.4 在Mac版Unity编辑器下的注意事项路径分隔符C#的Path.Combine方法会处理不同平台的路径分隔符问题但手动拼接字符串时请使用Path.Combine避免使用硬编码的\或/。文件访问权限如果你将Excel文件保存在Application.dataPath即Assets文件夹内Unity可能会尝试将其作为资源导入导致文件被锁定或修改。最佳实践如教程所示将导入的源Excel文件和导出的目标文件都放在Assets文件夹之外例如项目根目录的Config或Exports文件夹。EPPlus在macOS上的表现EPPlus是纯托管代码库在macOS的Unity编辑器下运行通常没有问题。但如果遇到问题可以尝试使用EPPlus的ExcelPackage.LicenseContext属性设置为NonCommercial如果你在非商业项目中使用或Commercial这有时能解决一些在非Windows系统上的初始化问题。7.5 扩展技巧处理复杂单元格与样式EPPlus的功能远不止读写文本和数字。通过它你可以创建专业的Excel报表单元格样式worksheet.Cells[A1].Style.Font.Bold true;worksheet.Cells[B2].Style.Fill.PatternType OfficeOpenXml.Style.ExcelFillStyle.Solid;worksheet.Cells[B2].Style.Fill.BackgroundColor.SetColor(System.Drawing.Color.LightBlue);设置列宽行高worksheet.Column(1).Width 20;worksheet.Row(1).Height 25;合并单元格worksheet.Cells[A1:C1].Merge true;创建简单图表仅限高级版本或特定场景虽然可行但在Unity编辑器工具中动态生成图表的需求较少且会使依赖复杂化一般建议将原始数据导出后由Excel自身或其它专业工具生成图表。最后一个非常重要的心得是保持编辑器工具的鲁棒性。在你的导入工具中加入详尽的日志输出和错误处理。当策划提供的Excel表格列数不对、格式错误时工具应该给出明确、友好的错误提示如“第X行第Y列的数据‘abc’无法转换为整数”而不是让Unity控制台抛出一堆令人困惑的异常。这能极大降低非技术人员的使用门槛和你的维护成本。
