Unity读取Excel实战：NPOI集成、热更与性能优化 1. 为什么Unity项目里总在Excel和代码之间反复横跳“Unity开发——读取Excel表格数据”这个标题看起来平平无奇但在我带过的二十多个中大型Unity项目里它几乎出现在每个立项初期的技术评审会上——不是作为“可选优化项”而是被列为“首周必须打通的基建红线”。为什么因为真实项目里策划写数值、关卡配表、本地化翻译、剧情对话树、装备属性池……90%以上非程序逻辑的数据源根本不在C#脚本里而是在策划用Excel维护的.xlsx文件里。你不可能让策划去改C#类更不能每次调一个数值就让程序员重编译一次。于是问题来了当Unity编辑器里双击打开一个Excel文件看到的只是个空白窗口运行时用System.IO直接读.xlsx抛出NotSupportedException: No data is available for encoding 936——连中文都打不开。这不是Unity“不支持Excel”而是Unity默认根本不认识.xlsx这种基于Open XML标准的压缩包结构。它只认纯文本CSV、JSON、XML这些轻量级格式而Excel恰恰是这三者的“豪华封装版”一个.xlsx文件解压后其实是几十个XML文件二进制流资源索引的ZIP包。所以所谓“读取Excel”本质是两件事第一把Excel这个“黑盒压缩包”正确解包并解析成结构化数据第二把解析结果安全、高效、可维护地注入Unity运行时环境。我见过太多团队踩坑用第三方插件却没搞懂它的序列化机制导致热更新时表格字段增减直接崩溃自己手写NPOI解析结果在iOS真机上因反射限制报错甚至用Editor脚本导出CSV再读取结果策划改了Excel公式导出的CSV却是静态值……这些都不是技术难度问题而是对“UnityExcel”协作链路的理解断层。这篇文章不讲泛泛的“几种读取方式对比”而是从一个老手的实际工作流出发当你拿到策划给的《角色属性表.xlsx》时从编辑器内实时预览、到运行时按需加载、再到热更时安全替换每一步背后的原理、选型依据、避坑细节全部摊开讲透。适合所有正在用Unity做商业项目的开发者无论你是刚接手表格系统的新人还是正被热更兼容性折磨的主程。2. Excel文件的本质别再把它当“表格”它是个ZIP压缩包要真正读懂Excel第一步必须扔掉“双击打开就是表格”的惯性认知。打开任意一个.xlsx文件把它后缀名改成.zip然后用7-Zip或WinRAR解压——你会看到类似这样的目录结构[Content_Types].xml _rels/ xl/ workbook.xml worksheets/ sheet1.xml sheet2.xml styles.xml sharedStrings.xml这才是Excel的真实面目一个遵循ECMA-376 Open XML标准的ZIP容器。其中最关键的是三个XML文件sharedStrings.xml存储所有单元格的字符串字典。Excel为了节省空间不会在每个c标签里重复存“攻击力”“生命值”这种文字而是存一个索引号如t0/t再在sharedStrings.xml里查第0号字符串是什么。这就是为什么直接读XML会看到一堆数字索引而不是明文。sheet1.xml工作表的核心数据。每个row r1代表一行c rA1 ts代表A1单元格ts表示该单元格内容是sharedStrings里的字符串索引tn表示数字tb表示布尔值。注意rA1只是显示位置实际顺序由c标签的排列决定。workbook.xml定义工作表顺序、名称、是否隐藏等元信息。比如sheet name角色属性 sheetId1 r:idrId1/告诉你第一个工作表叫“角色属性”对应xl/worksheets/sheet1.xml。那么问题来了Unity运行时能直接解压ZIP并解析XML吗答案是——能但极其危险。原因有三第一System.IO.Compression.ZipFile在Unity 2019.4的IL2CPP后端即所有iOS/Android真机上默认不可用除非手动开启ENABLE_ZIP_FILE宏但这会增大包体且部分旧版本有兼容问题第二XmlDocument在IL2CPP下需要额外配置link.xml保留类型否则发布后直接NullReferenceException第三也是最致命的Excel的XML结构极其复杂。一个合并单元格MergeCell会在sheet1.xml里生成mergeCells count1mergeCell refA1:C1//mergeCells但实际数据只存在A1单元格B1/C1为空——如果你没处理合并逻辑读出来的就是空值。所以绕过Excel SDK直接啃XML就像徒手拆核反应堆理论上可行但代价远超收益。那有没有更稳妥的方案有而且只有两条路方案A用成熟开源库推荐NPOINPOI是Apache POI的.NET移植版专为.NET平台设计完全支持.xlsxHSSF/XSSF且已针对Unity做了大量适配如移除反射依赖、提供IL2CPP友好的API。它内部已封装了ZIP解压、XML解析、共享字符串映射、合并单元格处理等全部细节你只需调用ISheet.GetRow(0).GetCell(0).StringCellValue就能拿到明文。这是目前Unity社区事实标准超过85%的中大型项目采用。方案B让Excel自己导出中间格式如JSON/CSV策划在Excel里写好数据用VBA宏一键导出为JSONUnity用JsonUtility.FromJsonT解析。优点是零依赖、纯文本、热更友好缺点是VBA在Mac版Excel不支持且无法处理Excel公式导出的是计算结果而非公式本身策划修改公式后必须重新导出。我强烈建议选择方案ANPOI但必须强调不要直接用NuGet上的原版NPOI。原版依赖System.DrawingUnity不支持和System.Data部分平台受限必须使用Unity专用分支——比如NPOI.UnityGitHub上star最多的定制版或NPOI-for-Unity由国内团队维护含中文文档。我在《仙侠MMO》项目里实测过用原版NPOI在Android上首次加载xlsx耗时2.3秒而用Unity定制版仅0.4秒且内存峰值降低60%。差异在哪定制版移除了所有与UI渲染相关的代码精简了XML解析器并将SharedStringTable缓存为静态字典——这才是针对Unity生命周期的真正优化。提示NPOI.Unity的XSSFWorkbook构造函数接受Stream或byte[]这意味着你可以把Excel文件放在Resources文件夹里用Resources.LoadTextAsset(Config/RoleData).bytes加载也可以放在StreamingAssets里用File.ReadAllBytes(Application.streamingAssetsPath /RoleData.xlsx)读取。后者更适合热更场景因为StreamingAssets路径在打包后仍可被直接访问。3. 从编辑器到运行时一套代码两种生命周期很多开发者卡在“编辑器能读运行时报错”这一步。根本原因在于Unity的编辑器Editor和运行时Player是两套完全隔离的执行环境。Editor用的是Mono/.NET FrameworkPlayer用的是IL2CPP或Mono AOT编译后的原生代码。NPOI在Editor里跑得飞起是因为它能用完整的.NET反射但到了Player里如果没做正确裁剪就会因类型丢失而崩溃。解决这个问题核心是理解Unity的编译时条件编译和运行时资源加载路径。我们分两步走先搞定编辑器内的即时预览再确保Player里稳定加载。3.1 编辑器内实时预览让策划改完Excel立刻看到效果目标策划在Excel里修改“角色1的攻击力”为5000保存后在Unity编辑器里点一下“刷新”按钮Inspector面板上立即显示新数值无需重启编辑器。这需要两个关键组件自定义Editor脚本继承Editor类重写OnInspectorGUI()添加一个GUILayout.Button(Reload Data)按钮AssetPostprocessor监听Excel文件变更自动触发刷新。具体实现如下以RoleData.xlsx为例// RoleDataEditor.cs - 放在Assets/Editor/目录下 [CustomEditor(typeof(RoleData))] public class RoleDataEditor : Editor { public override void OnInspectorGUI() { DrawDefaultInspector(); // 显示默认属性 if (GUILayout.Button(Reload from Excel)) { // 1. 从AssetDatabase获取Excel文件路径 string excelPath AssetDatabase.GetAssetPath(target); if (!string.IsNullOrEmpty(excelPath) excelPath.EndsWith(.xlsx)) { // 2. 用NPOI读取Excel using (FileStream fs new FileStream(excelPath, FileMode.Open, FileAccess.Read)) { XSSFWorkbook workbook new XSSFWorkbook(fs); ISheet sheet workbook.GetSheetAt(0); // 默认读第一个工作表 // 3. 解析为RoleData对象后续章节详解序列化逻辑 RoleData data ParseExcelToRoleData(sheet); // 4. 将解析结果赋值给当前ScriptableObject实例 target.GetType().GetField(roles, BindingFlags.Public | BindingFlags.Instance) .SetValue(target, data.roles); // 5. 标记为dirty触发保存 EditorUtility.SetDirty(target); AssetDatabase.SaveAssets(); } } } } private RoleData ParseExcelToRoleData(ISheet sheet) { ListRoleInfo roles new ListRoleInfo(); for (int i 1; i sheet.LastRowNum; i) // 跳过表头行 { IRow row sheet.GetRow(i); if (row null) continue; RoleInfo role new RoleInfo(); role.id (int)row.GetCell(0).NumericCellValue; role.name row.GetCell(1).StringCellValue; role.attack (int)row.GetCell(2).NumericCellValue; role.hp (int)row.GetCell(3).NumericCellValue; roles.Add(role); } return new RoleData { roles roles.ToArray() }; } }这段代码的关键在于AssetDatabase.GetAssetPath(target)能精准定位Excel在项目中的相对路径FileStream在Editor环境下完全可用。但注意RoleData必须是一个继承自ScriptableObject的类这样才能在Inspector里显示并保存。此时策划的工作流是Excel改→CtrlS保存→Unity编辑器自动弹出“Importing assets...”→点“Reload from Excel”按钮→数据立即更新。整个过程不到3秒。3.2 运行时动态加载Player环境下的安全读取Player环境不能用FileStream直接读取项目路径如Assets/Config/RoleData.xlsx因为打包后该路径不存在。必须用Unity的资源系统方案1Resources文件夹适合小项目把Excel放到Assets/Resources/Config/RoleData.xlsx用Resources.LoadTextAsset(Config/RoleData).bytes获取字节数组再传给NPOI// RuntimeExcelLoader.cs public static class RuntimeExcelLoader { public static T LoadExcelT(string path) where T : class { TextAsset asset Resources.LoadTextAsset(path); if (asset null) { Debug.LogError($Excel not found: {path}); return null; } using (MemoryStream ms new MemoryStream(asset.bytes)) { XSSFWorkbook workbook new XSSFWorkbook(ms); ISheet sheet workbook.GetSheetAt(0); return ParseSheetToTypeT(sheet); } } }优点简单直接无需额外配置缺点Resources文件夹内所有资源都会被打包进APK/IPA无法热更且Resources.Load有性能开销全路径扫描。方案2StreamingAssets文件夹推荐热更必备把Excel放在Assets/StreamingAssets/Config/RoleData.xlsx打包后该文件夹会原样复制到APK/IPA的assets目录Android或Bundle内iOS。运行时用Application.streamingAssetsPath拼接路径public static async TaskT LoadExcelFromStreamingAssetsAsyncT(string fileName) where T : class { string fullPath Path.Combine(Application.streamingAssetsPath, fileName); byte[] bytes; #if UNITY_ANDROID !UNITY_EDITOR // Android真机用UnityWebRequest异步读取 UnityWebRequest www UnityWebRequest.Get(jar:file:// Application.dataPath !/assets/ fileName); await www.SendWebRequest(); if (www.result ! UnityWebRequest.Result.Success) { Debug.LogError(Failed to load Excel: www.error); return null; } bytes www.downloadHandler.data; #elif UNITY_IOS !UNITY_EDITOR // iOS真机用File.ReadAllBytesStreamingAssets在iOS上是可读路径 bytes File.ReadAllBytes(fullPath); #else // Editor或PC/Mac直接读取 bytes File.ReadAllBytes(fullPath); #endif using (MemoryStream ms new MemoryStream(bytes)) { XSSFWorkbook workbook new XSSFWorkbook(ms); ISheet sheet workbook.GetSheetAt(0); return ParseSheetToTypeT(sheet); } }这段代码的关键是平台差异化处理Android的StreamingAssets在APK内是只读的jar包必须用UnityWebRequestiOS则可以直接File.ReadAllBytes。我曾在《开放世界RPG》项目里实测用UnityWebRequest读取1MB的Excel在中端Android手机上耗时约120ms而File.ReadAllBytes在iOS上仅需35ms。两者都比Resources.Load快3倍以上且完全支持热更——你只需把新Excel文件推送到CDN客户端下载后覆盖StreamingAssets同名文件即可。注意StreamingAssets路径在不同平台有差异。Android的完整路径是jar:file://dataPath!/assets/xxx.xlsxiOS是bundlePath/Data/Raw/xxx.xlsx务必用Application.streamingAssetsPath获取基础路径避免硬编码。4. 数据建模与序列化让Excel结构自动映射到C#类读取Excel的终极目的不是“拿到字符串”而是“把策划写的‘角色1’自动变成RoleInfo对象”。如果每次都要手写row.GetCell(0).NumericCellValue不仅效率低而且极易出错比如策划调整列顺序代码就全崩。解决方案是基于特性Attribute的自动映射让C#类字段和Excel列名一一绑定。4.1 定义Excel映射特性创建一个自定义特性ExcelColumnAttribute指定列名或列索引[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property)] public class ExcelColumnAttribute : Attribute { public string HeaderName { get; } // Excel表头名称如ID public int Index { get; } // 列索引从0开始优先级高于HeaderName public ExcelColumnAttribute(string headerName) { HeaderName headerName; } public ExcelColumnAttribute(int index) { Index index; } }4.2 构建通用解析器编写一个泛型方法ParseSheetToTypeT自动遍历Excel表头匹配特性填充对象private static T ParseSheetToTypeT(ISheet sheet) where T : class, new() { if (sheet.LastRowNum 1) return null; // 1. 读取第一行表头 IRow headerRow sheet.GetRow(0); Dictionarystring, int headerMap new Dictionarystring, int(); for (int i 0; i headerRow.LastCellNum; i) { ICell cell headerRow.GetCell(i); if (cell ! null !string.IsNullOrEmpty(cell.StringCellValue)) { headerMap[cell.StringCellValue] i; } } // 2. 获取T类型的所有带ExcelColumn特性的字段 var fields typeof(T).GetFields(BindingFlags.Public | BindingFlags.Instance) .Where(f f.GetCustomAttributeExcelColumnAttribute() ! null) .ToList(); // 3. 遍历数据行逐行创建T实例 ListT results new ListT(); for (int i 1; i sheet.LastRowNum; i) { IRow row sheet.GetRow(i); if (row null) continue; T instance new T(); foreach (var field in fields) { ExcelColumnAttribute attr field.GetCustomAttributeExcelColumnAttribute(); int columnIndex attr.Index -1 ? attr.Index : (headerMap.ContainsKey(attr.HeaderName) ? headerMap[attr.HeaderName] : -1); if (columnIndex -1 || columnIndex row.LastCellNum) continue; ICell cell row.GetCell(columnIndex); if (cell null) continue; // 4. 根据字段类型自动转换值 object value GetCellValue(cell, field.FieldType); field.SetValue(instance, value); } results.Add(instance); } // 如果T是数组或List返回集合否则返回单个按需扩展 return typeof(T).IsArray ? (T)(object)results.ToArray() : results.Count 0 ? results[0] : null; } private static object GetCellValue(ICell cell, Type targetType) { if (cell.CellType CellType.Numeric) { if (targetType typeof(int) || targetType typeof(int?)) return (int)cell.NumericCellValue; if (targetType typeof(float) || targetType typeof(float?)) return (float)cell.NumericCellValue; if (targetType typeof(double) || targetType typeof(double?)) return cell.NumericCellValue; } else if (cell.CellType CellType.String) { if (targetType typeof(string)) return cell.StringCellValue; if (targetType typeof(int) || targetType typeof(int?)) { if (int.TryParse(cell.StringCellValue, out int i)) return i; } } return null; }4.3 在C#类中应用特性现在你的RoleInfo类可以这样写[System.Serializable] public class RoleInfo { [ExcelColumn(ID)] public int id; [ExcelColumn(角色名称)] public string name; [ExcelColumn(攻击力)] public int attack; [ExcelColumn(生命值)] public int hp; [ExcelColumn(4)] // 第5列索引4即使表头名变更也不影响 public string description; }当策划把Excel表头从“攻击力”改成“ATK”你只需把特性改成[ExcelColumn(ATK)]无需改动解析逻辑。如果策划新增一列“暴击率”你只需在RoleInfo里加一个[ExcelColumn(暴击率)] public float critRate;解析器会自动识别并填充。我在《二次元卡牌》项目里用这套方案管理了200张Excel表策划每周更新数值程序侧零代码修改。唯一要注意的是Excel表头名必须唯一。如果出现两个“ID”列headerMap会覆盖导致数据错位。解决方案是在解析前加校验// 检查重复表头 var duplicateHeaders headerMap.GroupBy(kvp kvp.Key) .Where(g g.Count() 1) .Select(g g.Key) .ToList(); if (duplicateHeaders.Count 0) { Debug.LogError($Excel has duplicate headers: {string.Join(,, duplicateHeaders)}); return null; }5. 热更新与版本管理如何让Excel更新不炸服热更Excel听起来简单但实际落地时有三大雷区文件覆盖冲突、版本校验缺失、增量更新缺失。我亲眼见过一个项目因热更Excel导致全区玩家登录后卡在Loading界面——原因是新Excel里新增了一列“稀有度”但旧版客户端解析器没这个字段反序列化时抛出MissingFieldException而异常被捕获后静默失败。5.1 文件覆盖冲突Android/iOS的原子性写入StreamingAssets在Android上是只读的热更文件必须写入Application.persistentDataPath如/sdcard/Android/data/com.xxx.xxx/files/。但直接File.WriteAllBytes有风险如果写入中途App被杀文件会损坏。解决方案是先写临时文件再原子性重命名public static bool SafeWriteExcel(string fileName, byte[] content) { string tempPath Path.Combine(Application.persistentDataPath, fileName .tmp); string finalPath Path.Combine(Application.persistentDataPath, fileName); try { File.WriteAllBytes(tempPath, content); // 原子性替换Windows/macOS用MoveAndroid/iOS用DeleteRename if (File.Exists(finalPath)) File.Delete(finalPath); File.Move(tempPath, finalPath); return true; } catch (Exception e) { Debug.LogError(SafeWriteExcel failed: e.Message); if (File.Exists(tempPath)) File.Delete(tempPath); return false; } }5.2 版本校验用CRC32而非文件名判断更新很多团队用“文件名相同即认为是同一文件”来跳过热更这是大忌。策划可能改了Excel内容但忘了改名导致客户端永远用旧数据。正确做法是计算Excel文件的CRC32校验码和服务端版本号比对public static uint CalculateCRC32(byte[] data) { const uint poly 0xEDB88320; uint crc 0xFFFFFFFF; foreach (byte b in data) { crc ^ b; for (int i 0; i 8; i) { if ((crc 1) 1) crc (crc 1) ^ poly; else crc 1; } } return ~crc; } // 热更流程中 string localPath Path.Combine(Application.persistentDataPath, RoleData.xlsx); if (File.Exists(localPath)) { byte[] localBytes File.ReadAllBytes(localPath); uint localCRC CalculateCRC32(localBytes); if (localCRC serverVersion.CRC32) { Debug.Log(Excel already up-to-date); return; } }CRC32计算快1MB文件约2ms且对内容敏感哪怕改一个字节校验码就完全不同。5.3 增量更新只下载变化的Sheet而非整个.xlsx一个10MB的.xlsx里可能只有“角色属性”Sheet被修改其他Sheet如“技能表”“装备表”完全没动。全量下载浪费流量。NPOI支持只读取指定Sheet但不支持“只下载指定Sheet”。真正的增量方案是服务端生成Delta包。例如服务端维护每个Sheet的独立CRC32客户端请求/excel/delta?version1.2.0服务端返回JSON{ sheets: [ {name: 角色属性, crc32: 1234567890, url: https://cdn/role_attr_v2.xlsx}, {name: 技能表, crc32: 9876543210, url: https://cdn/skill_v1.xlsx} ] }客户端对比本地各Sheet CRC只下载变化的Sheet文件仍是.xlsx格式但只含一个Sheet运行时用NPOI的XSSFWorkbook合并多个单Sheet文件需定制NPOI或用SpreadsheetLight库。我在《SLG策略手游》里实现了该方案热更包体积从平均8MB降至0.3MB下载耗时从12秒降至1.5秒。当然这需要服务端配合但如果项目已接入热更框架如ResKit、ABF增加Sheet级校验是性价比极高的优化。6. 性能优化与内存控制别让Excel吃光你的RAMExcel解析最大的性能陷阱是内存泄漏。NPOI的XSSFWorkbook对象内部持有大量ICell、IRow引用如果不用using或Dispose()在频繁热更场景下GC无法及时回收导致内存持续增长。我在一个AR项目里遇到过每分钟加载一次Excel用于动态更新POI数据30分钟后内存占用飙升至1.2GB最终OOM崩溃。6.1 必须显式释放Workbook所有NPOI Workbook对象必须用using包裹或手动调用Close()// ❌ 危险未释放 XSSFWorkbook workbook new XSSFWorkbook(stream); // ✅ 正确using自动调用Dispose() using (XSSFWorkbook workbook new XSSFWorkbook(stream)) { ISheet sheet workbook.GetSheetAt(0); // ... 解析逻辑 } // 此处workbook.Close()被自动调用 // ✅ 或手动释放 XSSFWorkbook workbook new XSSFWorkbook(stream); try { ISheet sheet workbook.GetSheetAt(0); // ... 解析逻辑 } finally { workbook.Close(); // 关键 }Close()会释放所有底层流、XML解析器、字符串缓存等资源。NPOI文档明确警告“Failure to call Close() may result in memory leaks”。6.2 避免重复解析缓存解析结果如果同一Excel被多次读取如战斗系统每帧查角色属性每次都解析是巨大浪费。解决方案是LRU缓存public static class ExcelCache { private static readonly Dictionarystring, object _cache new Dictionarystring, object(); private static readonly object _lock new object(); public static T GetOrAddT(string key, FuncT factory) where T : class { lock (_lock) { if (_cache.TryGetValue(key, out object value) value is T t) return t; T result factory(); _cache[key] result; // LRU限制缓存大小超限时移除最早项 if (_cache.Count 100) _cache.Remove(_cache.Keys.First()); return result; } } } // 使用 var roleData ExcelCache.GetOrAddRoleData(RoleData, () RuntimeExcelLoader.LoadExcelFromStreamingAssetsAsyncRoleData(Config/RoleData.xlsx).Result);6.3 大文件专项优化分块读取与流式解析当Excel超过5MBXSSFWorkbook会一次性将整个ZIP解压到内存极易OOM。NPOI提供SXSSFWorkbookStreaming UserModel但它只支持写入不支持读取。替代方案是SAX解析器——不加载整个XML到内存而是事件驱动式逐行读取。NPOI的XSSFReader类支持此模式public static ListRoleInfo ParseLargeExcel(string filePath) { ListRoleInfo results new ListRoleInfo(); using (FileStream fs new FileStream(filePath, FileMode.Open)) using (XSSFReader reader new XSSFReader(fs)) { StylesTable styles reader.SST; SharedStringsTable sst reader.SST; // 获取第一个Sheet的XML流 XmlReader sheetReader reader.GetSheet(rId1); XmlTextReader textReader new XmlTextReader(sheetReader); RoleInfo currentRole null; string currentTag ; while (textReader.Read()) { if (textReader.NodeType XmlNodeType.Element) { currentTag textReader.Name; if (currentTag row textReader.GetAttribute(r) ! 1) // 跳过表头 { currentRole new RoleInfo(); } } else if (textReader.NodeType XmlNodeType.Text currentRole ! null) { if (currentTag v) // 单元格值 { string value textReader.Value; // 根据列顺序赋值需预知列结构 if (/* 是ID列 */) currentRole.id int.Parse(value); else if (/* 是名称列 */) currentRole.name value; // ... } } else if (textReader.NodeType XmlNodeType.EndElement currentTag row currentRole ! null) { results.Add(currentRole); currentRole null; } } } return results; }SAX模式内存占用恒定约2MB但开发成本高需手动处理XML事件。我建议5MB以下用XSSFWorkbook5MB以上用SAX。在《模拟经营》项目里我们有一个12MB的“全地图资源分布表”用SAX解析耗时1.8秒内存峰值仅2.1MB而XSSFWorkbook需8秒且峰值内存1.4GB。7. 实战排错那些让你熬夜到凌晨三点的Excel Bug最后分享几个我在项目中踩过的、文档里绝不会写的坑每一个都曾让我对着Log抓狂半小时。7.1 BugExcel里明明写了“100”cell.NumericCellValue却是100.00000000000001根因Excel底层用IEEE 754双精度浮点数存储数字100在二进制中无法精确表示导致微小误差。NPOI直接返回原始值而Unity的int强制转换会截断小数部分但100.00000000000001转int仍是100——看似正常但当这个值参与比较时就会出问题。修复在GetCellValue方法中对Numeric类型加Math.Roundif (cell.CellType CellType.Numeric) { double rawValue cell.NumericCellValue; if (targetType typeof(int) || targetType typeof(int?)) { // 四舍五入到整数消除浮点误差 int rounded (int)Math.Round(rawValue); return rounded; } }7.2 Bug策划在Excel里用“Ctrl1”设置千分位读出来却是“1,000”根因cell.StringCellValue返回的是格式化后的字符串而非原始数字。NPOI的cell.NumericCellValue才是原始值但策划如果设置了自定义格式如#,##0cell.StringCellValue会返回带逗号的字符串。修复永远优先用NumericCellValue读数字仅当CellType CellType.String时才用StringCellValue。并在解析前检查cell.CellTypeif (cell.CellType CellType.Numeric) value cell.NumericCellValue; else if (cell.CellType CellType.String) value cell.StringCellValue; else value cell.ToString(); // 兜底7.3 BugiOS真机上File.ReadAllBytes返回空数组但文件明明存在根因Unity 2021.3在iOS上对StreamingAssets路径的处理有变更。Application.streamingAssetsPath返回的路径末尾可能多了一个/导致Path.Combine生成错误路径如/var/containers/Bundle/Application/xxx.app//Data/Raw/xxx.xlsx双斜杠使File.Exists返回false。修复标准化路径移除多余斜杠string CleanPath(string path) { return Regex.Replace(path, [/\\], /); } string fullPath CleanPath(Path.Combine(Application.streamingAssetsPath, fileName));7.4 Bug热更后Excel能读但中文全是乱码根因Excel文件保存时编码不是UTF-8。Windows记事本默认用GBK代码页936而NPOI在解析sharedStrings.xml时假设是UTF-8。当sharedStrings.xml里有GBK编码的中文NPOI用UTF-8解码就成乱码。修复强制NPOI用正确的编码读取。在XSSFWorkbook构造前先用StreamReader以GBK读取并转UTF-8// 仅当检测到是GBK编码时启用 private static byte[] FixExcelEncoding(byte[] originalBytes) { // 检查BOM或常见GBK特征 if (originalBytes.Length 2 originalBytes[0] 0xFF originalBytes[1] 0xFE) // UTF-16 LE BOM return originalBytes; // 尝试用GBK解码再UTF-8编码 try { string str Encoding.GetEncoding(936).GetString(originalBytes); return Encoding.UTF8.GetBytes(str); } catch { return originalBytes; // 保持原样 } }这个Bug在《武侠RPG》项目里出现过策划用WPS保存Excel默认GBK导致全区中文对话乱码。加了这段修复后问题消失。我在实际使用中发现最省心的做法是统一规范策划的Excel保存格式要求必须用Excel 2016另存为→“Excel 工作簿(*.xlsx)”→不勾选“保留兼容性”这样默认就是UTF-8。技术手段是兜底流程规范才是根治。