排障手册¶
按你看到的现象组织,不按原因组织。找到你的症状,照着查。
Excel 打开文件时提示「发现不可读取的内容」¶
现象 —— 文件能生成,但 Excel 打开时报错并要求修复。
按顺序排查:
-
是不是往不支持的格式写了高级功能? 比如往 xls 写图片、往 csv 写批注。开一下降级回调就能看到:
-
是不是打开后另存,且原文件含图表 / 透视表 / 切片器? 这些部件本库只做「原样保留」。跨格式转换(比如 xlsm → xlsx)会丢失它们。 建议写回原格式,不要转换。
-
还是不行? 到 Issues 提问题, 附上原始文件和最小复现代码。这类问题几乎都依赖具体文件才能定位。
中文内容变成乱码¶
csv 文件最常见。原因是编码不对:
// 写 csv 时显式指定编码
Excel.Write("out.csv", sheet, new ExcelWriteOptions { CsvEncoding = Encoding.UTF8 });
net8.0 上的代码页编码
Encoding.GetEncoding(936) 这类代码页编码在 net48 由 BCL 自带;
在 net8.0 需要调用方先注册 CodePagesEncodingProvider.Instance。
日期读出来是一串数字(比如 45321)¶
Excel 内部把日期存成数字,靠数字格式决定显示成日期。
- 用
Excel.Open读 —— 库会根据单元格的数字格式自动识别为日期。 - 用
Excel.ReadSheet读裸数据 —— 拿到的是原始数字,需要自己转换。
另外注意 1904 日期系统(老版 Mac Excel):Workbook.Date1904 为 true 时基准日不同。
样式写到 xls / xlsb 后丢了¶
这是预期行为,不是 bug。看格式能力矩阵:
| 格式 | 样式支持 |
|---|---|
| xlsx / xlsm | 完整(字体、颜色、边框、对齐、换行) |
| xlsb / xls | 仅数字格式 |
解决:改用 xlsx。如果必须输出 xls,请通过 OnDegradation 回调确认到底丢了什么。
读大文件时内存爆了¶
三个办法,按推荐顺序:
-
拉取式枚举 —— 最灵活,可以提前终止:
-
流式回调 —— 写法最简单:
-
写大文件用流式写入器:
流式只支持 xlsx / xlsm
xlsb / xls 是二进制格式,暂不支持流式读写。
参见大文件与流式。
密码打开报错¶
- 本库只支持 OOXML Agile 加密(Excel 2013 及以上默认)。 更老的「标准加密」不支持,会提示「文件使用不支持的加密方式」。
- xls 不支持文件级密码,csv 也不支持。
- 密码错误会抛
LiteExcelException,消息是「打开密码不正确,无法解密文件。」
参见文件级密码。
图表 / 透视表保存后不见了¶
本库不创建、不编辑图表与透视表,只做「打开再保存时原样保留」。
保留能力取决于格式:
| 格式 | 图表 / 透视表 |
|---|---|
| xlsx / xlsm / xlsb | 打开再保存原样保留 |
| xls / csv | 会丢失 |
注意:如果你修改了含透视表的工作表,某些情况下本库会默认阻止保存(避免静默丢失),
此时会抛异常并说明原因。设 workbook.AllowFeatureLossOnSave = true 可放行。
合并单元格后只有左上角有值¶
Excel 的合并单元格只在左上角存值,其余位置为空 —— 这是 OOXML 规范,不是本库的问题。
读回时想每格都有值? 用 SheetData 的合并填充选项,或读回后自己按
Worksheet.MergedRanges 展开。
参见合并与行列。
数字变成科学计数法 / 显示成 1.23457E+11¶
这是 Excel 的显示行为,取决于单元格的数字格式。
常见格式代码见样式 § 数字格式速查。
AOT 发布后运行报反射相关异常¶
List<T> 映射用了反射。本库已用 [DynamicallyAccessedMembers] 标注,正常裁剪不会出问题。
如果仍报错,检查:
- 是否用了未标注的第三方序列化搭配本库
InvariantGlobalization设置是否影响了编码(csv 的代码页编码需要额外注册)
参见 AOT 兼容性。
还是没解决?¶
提 issue 时请附上:
- LiteExcel 版本号(
dotnet list package可查) - 目标框架(net48 / net8.0)
- 涉及的文件格式
- 最小可复现代码
- 如果涉及文件,说明是 LiteExcel 生成的还是 Excel 生成的