EasyExcel 工作表名称截断问题分析与解决方案

2025-05-04 17:12:20作者：郜逊炳

问题背景

在使用阿里巴巴开源的EasyExcel库（3.3.2版本）处理Excel文件时，开发者可能会遇到一个看似奇怪的问题：当尝试向同一Excel文件追加不同名称的工作表时，系统却抛出"The workbook already contains a sheet named..."的错误提示，尽管肉眼观察工作表名称确实各不相同。

问题本质

经过深入分析，这个问题源于Excel底层对工作表名称长度的限制与EasyExcel的处理逻辑：

Excel规范限制：Excel规定工作表名称（sheet name）的最大长度为31个字符
EasyExcel处理机制：EasyExcel在内部会对超长的工作表名称进行自动截断，只保留前31个字符
冲突产生原因：当多个工作表名称的前31个字符相同时，即使完整名称不同，也会被系统判定为名称冲突

问题复现

以下代码示例可以复现该问题：

@Test
public void repeatedWrite2() {
    String fileName = "test.xlsx";
    try (ExcelWriter excelWriter = EasyExcel.write(fileName).build()) {
        for (int i = 0; i < 5; i++) {
            // 工作表名称长度超过31个字符
            WriteSheet writeSheet = EasyExcel.writerSheet(i, "AGT_BUILDER_PUB_ACCT_INFO_20220" + i)
                .head(DemoData.class)
                .build();
            List<DemoData> data = data();
            excelWriter.write(data, writeSheet);
        }
    }
}

在这个例子中，虽然每个工作表名称末尾的数字不同（"AGT_BUILDER_PUB_ACCT_INFO_202200"到"AGT_BUILDER_PUB_ACCT_INFO_202204"），但由于名称前31个字符完全相同，EasyExcel会认为这些是重复的工作表名称。

解决方案

针对这个问题，开发者可以采取以下几种解决方案：

1. 控制工作表名称长度

确保工作表名称不超过31个字符，并且在关键位置（如前31个字符内）包含足够的区分度：

// 优化后的工作表名称
String sheetName = "ACCT_20220" + i;  // 确保前31个字符能区分不同工作表

2. 使用更短的命名策略

采用更简洁的命名方式，如：

使用有意义的缩写
将关键区分信息放在名称前部
避免冗余信息

3. 添加唯一标识符

在名称前31个字符内加入足够区分的标识：

String sheetName = "ACCT_" + UUID.randomUUID().toString().substring(0, 8) + "_" + i;

4. 自定义名称处理逻辑

实现自定义的SheetName策略，确保名称唯一性：

public class UniqueSheetNameGenerator {
    private static final int MAX_LENGTH = 31;
    
    public static String generate(String baseName, int index) {
        String uniquePart = "_" + index;
        int maxBaseLength = MAX_LENGTH - uniquePart.length();
        if (baseName.length() > maxBaseLength) {
            baseName = baseName.substring(0, maxBaseLength);
        }
        return baseName + uniquePart;
    }
}