跳转至

排障手册

按你看到的现象组织,不按原因组织。找到你的症状,照着查。


Excel 打开文件时提示「发现不可读取的内容」

现象 —— 文件能生成,但 Excel 打开时报错并要求修复。

按顺序排查:

  1. 是不是往不支持的格式写了高级功能? 比如往 xls 写图片、往 csv 写批注。开一下降级回调就能看到:

    var wb = Excel.Create();
    wb.AllowFeatureLossOnSave = false;   // 严格模式:有降级直接抛异常
    
  2. 是不是打开后另存,且原文件含图表 / 透视表 / 切片器? 这些部件本库只做「原样保留」。跨格式转换(比如 xlsm → xlsx)会丢失它们。 建议写回原格式,不要转换。

  3. 还是不行? 到 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 回调确认到底丢了什么。


读大文件时内存爆了

三个办法,按推荐顺序:

  1. 拉取式枚举 —— 最灵活,可以提前终止:

    foreach (var row in Excel.EnumerateRows("big.xlsx", "Sheet1"))
    {
        // 逐行处理,内存里只保留当前行
    }
    
  2. 流式回调 —— 写法最简单:

    Excel.StreamRows("big.xlsx", "Sheet1", row => { /* ... */ });
    
  3. 写大文件用流式写入器:

    using var w = Excel.CreateWriter("big.xlsx");
    foreach (var item in source)
        w.WriteRow(item.Id, item.Name);
    

流式只支持 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 的显示行为,取决于单元格的数字格式。

ws.Cell("A1").Style = new CellStyle { NumberFormat = "0" };   // 按整数显示

常见格式代码见样式 § 数字格式速查。


AOT 发布后运行报反射相关异常

List<T> 映射用了反射。本库已用 [DynamicallyAccessedMembers] 标注,正常裁剪不会出问题。

如果仍报错,检查:

  1. 是否用了未标注的第三方序列化搭配本库
  2. InvariantGlobalization 设置是否影响了编码(csv 的代码页编码需要额外注册)

参见 AOT 兼容性。


还是没解决?

提 issue 时请附上:

  • LiteExcel 版本号(dotnet list package 可查)
  • 目标框架(net48 / net8.0)
  • 涉及的文件格式
  • 最小可复现代码
  • 如果涉及文件,说明是 LiteExcel 生成的还是 Excel 生成的

→ 提交 issue