1. 项目概述当Unity开发者遇上Excel如果你正在用Unity开发游戏或者应用并且需要处理数据导出、存档、配置表读取这类功能那么“表格存储”这个问题大概率已经让你头疼过了。Unity自带的PlayerPrefs存点简单键值对还行但面对稍微复杂一点的结构化数据比如玩家背包里几十种物品、游戏关卡配置表、或者运行时生成的大量日志数据它就完全不够看了。直接读写.txt或.json文件是一种选择但当你需要把数据交给策划、运营或者自己用Excel打开分析时还得手动转换格式非常麻烦。这时候一个很自然的想法就是能不能让Unity直接生成或读取Excel文件.xlsx毕竟Excel是数据处理和交换的“世界语”。网上搜一圈你会发现很多讨论都指向一个.NET库EPPlus。这是一个在.NET生态里非常流行、功能强大的开源库专门用于操作Office Open XML格式也就是.xlsx的文件不需要在机器上安装Microsoft Office。然而当你兴冲冲地把EPPlus的DLL拖进Unity项目在编辑器里测试一切正常满心欢喜地打包成PC、安卓或WebGL版本时很可能就会遭遇当头一棒——构建失败或者运行时抛出DllNotFoundException或ReflectionTypeLoadException。这正是标题里“烦恼”二字的由来。这篇内容就是基于我多次在Unity项目中集成EPPlus的实战经验帮你把这条路彻底走通从原理到避坑一次讲清楚。2. EPPlus与Unity的兼容性核心难题为什么一个优秀的.NET库在Unity里用起来会这么折腾根本原因在于Unity所使用的脚本后端和**.NET兼容性级别**。2.1 Unity的脚本后端Mono vs IL2CPPUnity支持两种脚本后端Scripting BackendMono传统的后端使用即时编译JIT。它允许在运行时动态加载和编译代码对第三方.NET库的兼容性相对较好因为可以直接运行托管DLL。IL2CPPUnity大力推广的后端它将C#代码先编译成中间语言IL再转换成C代码最后编译成平台原生代码。它使用提前编译AOT能带来更好的性能和安全性但牺牲了部分动态特性。IL2CPP对反射、动态代码生成等有严格限制。EPPlus库内部大量使用了System.Reflection反射和System.Xml等特性这些在IL2CPP下可能会因为AOT编译的静态分析无法覆盖所有代码路径而导致运行时错误。因此如果你的项目目标是支持WebGL、iOS或追求最高性能而启用IL2CPP那么原生EPPlus库很可能无法直接工作。2.2 .NET兼容性级别API Compatibility Level这是Unity项目设置中的一个关键选项Player Settings-Other Settings-Configuration。它决定了你的项目可以访问哪些.NET框架的API。.NET Standard 2.0/2.1较新的、跨平台的标准。理论上兼容性最好但Unity对其支持尤其是通过Mono后端可能仍有一些历史遗留问题。.NET Framework如.NET 4.x或.NET Framework这是最完整的API集合。EPPlus通常依赖于.NET Framework 4.5或更高版本中的一些程序集比如System.Drawing用于处理图表、图片、WindowsBase、PresentationCore等。.NET 2.0 Subset一个非常精简的API子集只包含Unity认为跨平台安全的部分。这是默认选项也是绝大多数问题的根源。在这个级别下像System.IO.CompressionEPPlus用来处理ZIP包因为.xlsx本质是ZIP、System.Reflection.Emit等关键命名空间可能不可用或功能不全。当你将EPPlus的DLL放入项目Unity会尝试解析它的依赖。如果依赖的程序集如PresentationCore.dll不在.NET 2.0 Subset中或者不在Unity的许可程序集列表里在编辑器里因为编辑器运行在完整的.NET Framework环境下可能正常但构建独立应用时Unity的构建管线不会将这些“不被允许”的程序集打包进去从而导致构建失败或运行时找不到依赖。注意网络上2015-2017年的老帖子普遍结论是“EPPlus与Unity不兼容”主要是因为当时Unity的.NET支持尚不完善且IL2CPP还未成为主流。现在情况已有所不同通过正确的配置可以解决大部分问题。3. 实战在Unity中成功集成EPPlus的完整流程下面我将以Unity 2022.3 LTS版本为例演示如何一步步配置让EPPlus在编辑器和各平台构建中都能正常工作。我们的目标是在PC独立平台Standalone上成功运行。3.1 获取正确版本的EPPlus库首先不建议直接下载EPPlus官网的二进制包因为其依赖可能过于复杂。最佳途径是通过NuGet获取针对.NET Standard 2.0编译的版本这是兼容性最好的版本。使用NuGet获取如果你熟悉命令行可以安装nuget.exe然后执行nuget install EPPlus -Version 6.2.10 -OutputDirectory ./Packages找到生成的lib/netstandard2.0/EPPlus.dll。或者更简单的方法是访问 nuget.org 直接下载.nupkg文件将其后缀改为.zip后解压同样找到lib/netstandard2.0/EPPlus.dll。关键同时获取依赖的DLL。EPPlus 6.x 版本的核心依赖是System.Drawing.Common但为了跨平台我们需要一个纯托管的实现。实际上对于.NET Standard 2.0版本EPPlus已经将大部分依赖内化或转移了。但根据历史经验我们可能需要手动补充一些Unity构建时缺失的程序集。一个可靠的来源是Unity安装目录或创建一个简单的.NET Core控制台项目引用EPPlus后查看其输出目录。3.2 Unity项目配置步骤导入DLL在Unity项目的Assets文件夹下创建一个Plugins文件夹如果不存在。将EPPlus.dll复制进去。Unity会自动将其识别为插件。修改API兼容性级别打开Project Settings-Player-Other Settings。找到Configuration下的Api Compatibility Level。将其从默认的.NET Standard 2.0或.NET 2.0 Subset改为.NET Framework。这一步至关重要它解锁了完整的.NET Framework API确保EPPlus所需的所有类型都可用。同时检查Scripting Backend为了最大兼容性暂时先选择Mono。等所有功能在Mono下稳定后再尝试IL2CPP。处理缺失的程序集关键避坑点 即使切换到.NET Framework在构建PC平台时你可能还是会遇到类似“PresentationCore.dllis referenced but not found”的错误。这是因为Unity在构建时默认只会打包它“白名单”内的系统程序集。解决方案将这些缺失的系统DLL手动放入Plugins文件夹。去哪里找最简单的方法是在你的Windows系统目录如C:\Windows\Microsoft.NET\Framework64\v4.0.30319或C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2中搜索。通常需要补充的DLL包括PresentationCore.dllWindowsBase.dllSystem.Xaml.dllSystem.Deployment.dll操作将这些DLL也复制到Assets/Plugins目录下。对于PCWindows构建这通常能解决问题。注意这些是微软官方的.NET Framework DLL仅供Windows平台使用。如果你的目标平台是macOS、Linux或移动端此方法不适用需要寻找其他方案见下文跨平台部分。针对构建目标的特殊设置在Project Settings-Player-Other Settings-Configuration中确保Allow ‘unsafe’ Code是勾选的EPPlus可能用到。在Project Settings-Player-Publishing Settings下确保Enable Internal Profiler未勾选避免冲突。3.3 编写一个简单的测试脚本创建一个C#脚本ExcelTest.cs挂载到场景中的空物体上。using UnityEngine; using System.IO; using OfficeOpenXml; // EPPlus的命名空间 using System.Diagnostics; public class ExcelTest : MonoBehaviour { void Start() { // 设置EPPlus的许可证上下文社区版无需购买但需要设置 ExcelPackage.LicenseContext LicenseContext.NonCommercial; // 1. 创建一个新的Excel包 using (var package new ExcelPackage()) { // 添加一个工作表 var worksheet package.Workbook.Worksheets.Add(玩家数据); // 2. 写入一些数据 worksheet.Cells[1, 1].Value 玩家ID; worksheet.Cells[1, 2].Value 玩家名; worksheet.Cells[1, 3].Value 等级; worksheet.Cells[1, 4].Value 金币; worksheet.Cells[2, 1].Value 1001; worksheet.Cells[2, 2].Value Unity大师; worksheet.Cells[2, 3].Value 99; worksheet.Cells[2, 4].Value 999999; worksheet.Cells[3, 1].Value 1002; worksheet.Cells[3, 2].Value EPPlus测试员; worksheet.Cells[3, 3].Value 50; worksheet.Cells[3, 4].Value 5000; // 3. 自动调整列宽 worksheet.Cells[worksheet.Dimension.Address].AutoFitColumns(); // 4. 定义保存路径在Unity中使用Application.persistentDataPath是跨平台的安全选择 string savePath Path.Combine(Application.persistentDataPath, PlayerData.xlsx); // 5. 保存文件 FileInfo excelFile new FileInfo(savePath); package.SaveAs(excelFile); UnityEngine.Debug.Log($Excel文件已保存至: {savePath}); // 6. 可选尝试用系统默认程序打开它仅在某些平台有效 if (Application.platform RuntimePlatform.WindowsPlayer || Application.platform RuntimePlatform.WindowsEditor) { Process.Start(new ProcessStartInfo(savePath) { UseShellExecute true }); } } } }在编辑器里运行你应该能在控制台看到日志并在Application.persistentDataPath对应的目录Windows上通常在AppData/LocalLow/[公司名]/[产品名]下找到生成的PlayerData.xlsx文件用Excel打开检查内容。3.4 构建独立应用并测试在Unity编辑器中进行上述所有配置。执行File - Build Settings选择PC, Mac Linux Standalone目标平台选Windows。点击Build选择一个输出文件夹。如果构建成功运行生成的.exe文件。程序会在其自身的persistentDataPath下生成Excel文件。对于Windows独立应用这个路径通常是C:\Users\[用户名]\AppData\LocalLow\[公司名]\[产品名]\PlayerData.xlsx。如果构建失败请仔细查看Unity Console中的错误信息。最常见的错误仍然是缺少依赖程序集。根据错误信息提示的缺失DLL名称重复3.2 第3步将其添加到Plugins文件夹。4. 跨平台与IL2CPP的进阶挑战与解决方案让EPPlus在Windows Mono后端下工作只是第一步。真正的挑战在于其他平台和IL2CPP。4.1 非Windows平台macOS, Linux, Android, iOS手动添加PresentationCore.dll等Windows特有的.NET Framework DLL的方案显然行不通。对于这些平台核心思路是避免使用依赖特定Windows Presentation Foundation (WPF) 或完整.NET Framework的EPPlus功能。EPPlus的核心功能单元格读写、格式、公式在.NET Standard 2.0版本下是纯托管的不依赖原生Windows组件。理论上只要Unity的Mono或IL2CPP支持.NET Standard 2.0的API就应该能运行。问题在于一些高级功能如图表ExcelChart、图片处理特别是涉及System.Drawing的在非Windows环境下可能失效因为System.Drawing.Common在非Windows系统上依赖本地图形库如libgdiplus而Unity环境可能没有。解决方案功能裁剪只使用EPPlus的基本数据读写功能。如果你的需求只是生成数据表格不涉及复杂格式和图表那么跨平台成功的几率很高。使用替代库对于严格的跨平台需求可以考虑其他方案NPOI一个老牌的.NET POI库读写.xls和.xlsx。它更底层对平台依赖相对较小但在Unity中的集成同样需要处理依赖和IL2CPP兼容性问题。将数据导出为CSV这是最通用、最跨平台的方案。Unity中可以用StreamWriter轻松生成CSV文件。缺点是丢失了格式、多工作表等Excel特性但任何平台都能用文本编辑器或Excel打开。服务端生成将数据通过网络发送到服务器由服务器运行在完整的.NET环境使用EPPlus生成Excel文件再供用户下载。这完全规避了客户端的兼容性问题。4.2 IL2CPP脚本后端IL2CPP的AOT特性是EPPlus这种重度使用反射的库的“天敌”。核心问题EPPlus在运行时通过反射动态创建类型、加载属性这些动态代码路径IL2CPP的静态分析无法提前预知导致在构建时被裁剪掉进而引发运行时异常如MissingMethodException。解决方案使用link.xml文件来告诉IL2CPP链接器保留特定的类型和程序集。在Assets文件夹下创建一个名为link.xml的文本文件。编辑其内容指定需要保留的EPPlus相关类型。由于EPPlus内部类型很多最保险的方式是保留整个程序集linker assembly fullnameEPPlus preserveall/ assembly fullnameSystem.Drawing.Common preserveall/ !-- 保留System.Private.CoreLib中的一些反射相关类型 -- assembly fullnameSystem.Private.CoreLib type fullnameSystem.Reflection.* preserveall/ /assembly /linker这只是一个示例实际需要的保留范围可能更广。IL2CPP的链接问题通常需要反复试验和根据运行时错误日志来调整link.xml。重要提示即使使用了link.xml也无法保证EPPlus的所有功能在IL2CPP下100%工作特别是那些依赖动态发射Emit的极端功能。对于生产环境如果必须使用IL2CPP务必对EPPlus的所有使用场景进行详尽的跨平台测试。5. 常见问题排查与实战心得5.1 构建错误“DllNotFoundException” 或 “The dll is not allowed to be included”症状在编辑器里运行正常构建时失败错误信息指向某个系统DLL。原因Unity构建管线没有将所需的依赖DLL打包进去。解决确认Api Compatibility Level已设置为.NET Framework。将错误信息中提到的缺失的.dll文件例如System.Deployment.dll从你的Windows系统目录复制到Unity项目的Assets/Plugins文件夹。对于非Windows系统专用的DLL可以尝试从Unity的安装目录如Editor\Data\MonoBleedingEdge\lib\mono\4.7.1-api中寻找对应的托管DLL但要注意版本兼容性。5.2 运行时错误“System.Reflection.ReflectionTypeLoadException”症状在编辑器或运行时加载类型失败。原因依赖冲突或缺失或者在不兼容的API级别下运行。解决确保使用的是针对.NET Standard 2.0编译的EPPlus版本。清理项目并重新导入所有DLL删除Library文件夹后重新打开Unity。检查是否有其他插件引入了不同版本的相同程序集如System.IO.Compression导致冲突。5.3 在WebGL平台上的特殊处理WebGL平台由于其特殊的沙箱环境和WASM运行时对文件系统访问和线程有严格限制。EPPlus在WebGL中基本不可用因为它涉及大量的文件I/O和可能的线程操作这些在WebGL中要么受限要么行为不同。替代方案考虑在WebGL平台使用纯前端的JavaScript库来生成Excel。例如可以使用SheetJS开源或ExcelJS。通过Unity的JSLIBJavaScript交互来调用这些库。这需要较强的前端集成能力但这是目前WebGL导出Excel最可行的路径。5.4 性能与内存考量EPPlus在创建大型Excel文件数万行时可能会消耗较多内存因为它在内存中维护整个文档对象模型DOM。优化建议对于流式大数据写入可以使用ExcelPackage的Workbook.CreateWorksheet()并配合ExcelRange.Value逐批设置值但注意EPPlus不是为流式处理设计的。及时释放资源确保ExcelPackage对象在using语句块中或手动调用Dispose()。如果只是生成简单报表考虑直接生成CSV或HTML表格性能开销小得多。5.5 个人实操心得版本锁定一旦找到一个能在你所有目标平台上稳定工作的EPPlus版本例如6.2.10就在项目中锁定它不要轻易升级。新版本可能会引入新的依赖或API变化。隔离与封装不要在你的游戏逻辑代码中到处散落EPPlus的调用。应该创建一个专门的ExcelService或DataExporter类来封装所有与Excel相关的操作。这样当未来需要更换方案比如换成CSV导出时影响范围最小。备选方案永远存在在项目初期就评估是否真的必须用Excel。如果只是开发团队内部使用CSV可能更简单。如果需要丰富的格式可以考虑生成PDF使用像QuestPDF这样的库或HTML报告。构建农场/CI/CD如果你在团队中使用自动化构建记得将那些手动添加到Plugins的额外系统DLL也纳入版本控制如Git LFS或者确保构建服务器上有相同的环境。6. 总结与最终建议回到最初的问题“烦恼表格存储的朋友你知道EPPlus吗” 现在答案很明确了我知道它很强大但在Unity里用它就像请一位重量级嘉宾来参加一个有着严格安检和空间限制的派对——你需要做大量的准备工作并且要接受他可能无法表演所有节目。我的最终建议是分层的如果你的项目仅面向Windows PC平台且可以使用Mono后端按照本文的配置步骤切换API级别、补充必要DLLEPPlus是一个可靠的选择。它能提供强大的Excel生成能力。如果你的项目需要面向多平台包括PC且必须使用IL2CPP请做好心理准备你需要花费大量时间配置link.xml并进行全面测试。优先考虑仅使用EPPlus的核心数据读写功能并准备好备选方案如CSV。如果你的项目包含WebGL或移动端Android/iOS不建议在客户端直接使用EPPlus。对于WebGL转向基于JavaScript的浏览器端方案对于移动端考虑将数据上传到服务器由服务器生成Excel后供用户下载或者使用设备本地可用的、更轻量的数据交换格式。Unity生态中一直缺少一个官方、强大且开箱即用的跨平台Excel操作库这确实是一个痛点。EPPlus是目前最接近的解决方案但它的集成成本不低。在决定使用它之前务必用一个小型测试项目在你的所有目标平台和构建配置上跑通整个流程评估其稳定性和性能再将其引入正式项目。毕竟在游戏开发中稳定性和跨平台兼容性往往比一个酷炫的数据导出功能更重要。