先说结论：EasyPOI 基于模板导出 Excel 时，行高永远不可能像在 Excel 里手动输入那样“自动变高”。这跟 EasyPOI 本身没关系，而是所有基于 Apache POI 生成 .xlsx 的方案都会碰到的机制问题。你看到的现象通常是：模板里明明设置了自动换行，导出后数据多几行时，文字却被截断、遮住，行高还保持原样，用户打开文件还得手动拖一下行边界才正常。
这篇文章是我处理某仓库管理系统的导出报表时的完整记录：从怀疑 EasyPOI 到翻 POI 源码，再到写出通用后置处理工具，最后在项目里稳定跑了半年。我会把定位过程、代码实现、备选方案和几个坑都整理出来，给在 EasyPOI 行高上卡住的朋友直接抄作业。
1. 先确认症状与最小复现：为什么模板导出后行高成了“死”的
1.1 现象还原：数据长于预设高度就截断
业务需求是这样的：按模板导出月度明细表，最后一列是“备注”，用户可能填几十个字，也可能填几百个字。模板里给备注列设了自动换行，数据列也只有一行的高度。刚开始我预判 EasyPOI 应该能自动处理，结果一测就翻车——导出文件打开后，备注列的文本被压成一行多字的窄条，行高保持模板设置的默认值，第二行内容被上行遮挡。
后来我又做了个更简单的复现：模板中一个单元格写入 100 个字符，开启 wrapText，导出后用 Apache POI 读取该行高度，发现getHeightInPoints()返回的还是模板设定的数值，而 Excel 客户端打开后也不会自动重新计算。这就说明：行高在 xlsx 文件里就是一个存死的数值，生成文件的时候没有算，文件里就没有正确的高度信息。
1.2 最小复现代码：一个模板一个 main 方法就能触发
用 EasyPOI 的模板导出，最经典的方式如下：
public void demoExport() { TemplateExportParams params = new TemplateExportParams("template.xlsx"); Map<String, Object> map = new HashMap<>(); map.put("remark", "这是一段很长的备注内容，可能有好几行，模板里的行高根本不够显示"); Workbook workbook = ExcelExportUtil.exportExcel(params, map); try (FileOutputStream fos = new FileOutputStream("output.xlsx")) { workbook.write(fos); } catch (IOException e) { e.printStackTrace(); } }模板中只需要在数据行某一列写上{{remark}}占位符，然后把该列设为自动换行即可。运行后打开output.xlsx，就能看到前面说的截断现象。这个复现过程 5 分钟就能完成，建议先跑一遍，方便后续验证修复效果。
1.3 拆到底层：POI 写入行高的规则
要理解为什么“自动换行”没生效，得知道 Excel 的存储逻辑。xlsx 中每一行的行高记录在<row>标签的ht属性里，例如<row r="5" ht="15" customHeight="1">。如果这个属性不存在，Excel 打开时会用默认行高（通常是 15 磅）；但只要模板里设置了行高，导出后ht就会被模板值覆盖。
Apache POI 在生成文件时，本质上是把内存中的 row 对象序列化成 XML。它不会读取单元格文本内容去推算文本高度，也不会因为wrapText=true就自动调高ht。这是设计如此——文件格式里“自动换行”只是一个显示标志，真正的行高必须由写入方明确指定。
生活化类比：这就像写 Word 文档时用的是“固定行距”，不是“单倍行距”。固定行距下你怎么敲回车，行高都不会变，除非你自己手动调。模板导出也一样，模板行高就是固定行距，EasyPOI 不会帮你从固定行距切到自动行距。
2. 排查链路：从调大模板高度到翻进 POI 源码
2.1 第一条路：把模板行高调大，能解决但很难看
我第一个想法很简单：既然模板行高是固定的，那我在模板里直接把备注行的行高调成很大，比如 60 磅，不就能容纳 3 行了吗？
实测确实可以显示更多内容，但问题也很明显：内容只有一行时，行高依然 60 磅，原本紧凑的表格被拉得稀稀拉拉，业务方直接吐槽“不细看以为每行数据都空了三行”。而且备注内容超过 3 行时依旧截断，这是一个“永远在追赶”的方案，没办法预测用户到底会填多长。这个方法只适合内容长度几乎不变的固定场景，不适合动态数据。
2.2 第二条路：怀疑压到了 EasyPOI 的字段映射问题上
走这条路是因为我发现有些行文本能换行显示，有些行不能，起初以为是字段映射出问题。于是我把模板中的占位符从一个变成多个，又试了{{$fe:list}}宏、list 数据源填充，测试后确认：占位符替换本身没有问题，只是填充后的行高没有跟随内容更新。EasyPOI 把模板里的 row 读出来做占位符替换后，复制到目标 workbook 时原样保留了 row 的ht值，所以高度才“冻结”了。
2.3 顺着调用链确认根因
秉着“不能用玄学解释问题”的习惯，我直接翻了 EasyPOI 源码和 POI 源码。EasyPOI 的模板导出核心流程是先解析模板 workbook，再克隆相关 sheet，最后做文本替换。在克隆 sheet 时，row 对象直接流转到新文件；替换文本时，EasyPOI 只调用了cell.setCellValue()，没有调用任何高度重新计算逻辑。
Apache POI 这边更直接，XSSFSheet里根本没有“根据文本算行高”的现成 API。网上有人建议sheet.autoSizeColumn()，注意这个方法是调整列宽的，调整依据是列内最长文本的字符数，跟行高完全没关系，并且对中文支持极差——它按英文字符宽度估算，中文列宽经常算得不够。
所以根因清晰了：找一个拿到数据后的“行高修正时机”，自己把该行的实际高度算出来，强制写回去。用 POI 的行话就是：
row.setHeightInPoints(height);只要把每个数据行的height算对，模板导出的表就能真正做到“看起来像自动适配”。
3. 主方案：导出后遍历数据行，按内容动态回写行高
3.1 整体思路：后处理不能只算一个固定高度
既然 EasyPOI 不帮我们算，那就自己算。核心逻辑是：拿到导出的 workbook 后，遍历需要修正的区域，对每一个单元格先估算文本按当前列宽换行后的行数，再取最大行数乘以单行高度，得到该行的目标高度。
这里有个关键认知：同一行里多个单元格都可能换行，行高应该由这一行里所有“需要最高”的单元格共同决定，所以不能按列单独算再求和，而是取最大值。
3.2 估算文本行数：按字符宽度换行而不是按长度
文本换行行数的估算，绕不开字体宽度。同一个单元格里，中文字符和英文字符占的宽度完全不同，直接用text.length()去整除列宽，误差很大。我最终采用的方案是逐字符遍历：
private int calculateLines(String text, double colWidthPx, Font font) { if (text == null || text.isEmpty()) { return 1; } double lineWidth = 0; int lines = 1; for (char c : text.toCharArray()) { if (c == '\n') { lines++; lineWidth = 0; continue; } double charWidth = getCharWidth(c, font); lineWidth += charWidth; if (lineWidth >= colWidthPx) { lines++; lineWidth = charWidth; } } return lines; }getCharWidth的简化估算方法是：中文和全角标点宽度约为字号磅值对应的像素，西文字母和数字约为中文字宽的 0.5 倍。用 11 号字举例，中文一个字约 14.7px（11 磅 × 1.333），英文一个字符约 7px：
private double getCharWidth(char c, Font font) { int fontSize = font.getSize(); return isChinese(c) ? fontSize * 1.333 : fontSize * 1.333 * 0.5; }3.3 列宽换算：从 Excel 列宽单位到像素
POI 的getColumnWidth()返回的是以 1/256 字符宽度为单位的整数值。例如某列宽为 20，单位换算为像素可以用经验公式：
double colWidthPx = (sheet.getColumnWidth(colIndex) / 256.0) * 7.0;这里的 7 表示默认字体下一个字符约 7px，但要注意它是对西文字符的估算。为了和前面的中文字宽计算保持一致，我直接以“列能容纳多少个中文字符”为基准，把列宽像素再除以中文字宽：
int charsPerLine = (int) (colWidthPx / charWidthPx); int lines = (int) Math.ceil((double) text.length() / charsPerLine);这个方法更简单，误差也在可接受范围内。如果列宽较窄，单元格中英文占比又高，估算出来的行数可能偏大少；这时可以把西文字符按 0.5 权重做加权长度再计算，和上面的逐字符方案结合。
3.4 单行高度取值：不要只用字号，要加行距系数
Excel 里一行 11 号字大概需要 14.5~15 磅的高度，也就是说单行高度 = 字体磅值 × 约 1.4。这个系数不是固定技术值，是经验值，我用 1.5 作为默认，宁可稍微偏大一点，也不要出现“算完仍然被截断”的投诉。
最终计算目标行高的方法：
private float calcRowHeight(List<String> texts, double[] colWidthsPx, Font font) { int maxLines = 1; for (String text : texts) { int lines = calculateLines(text, colWidthsPx[i], font); maxLines = Math.max(maxLines, lines); } return maxLines * font.getSize() * 1.5f; }然后对每一行：
Row row = sheet.getRow(rowIndex); row.setHeightInPoints(calcRowHeight(...));以上是核心逻辑，真正生产环境里还要考虑合并单元格、表头过滤、空文本等情况，下面第 5 节我会给出完整可用的封装类。
4. 备选方案对比：模板预留高度与纯手工建表的取舍
4.1 方案 B：模板中把数据行行高设为最大容忍值
如果你实在不想写代码，最快的方法就是在模板里预留足够大的行高。比如备注限制 500 字，按列宽估算最多 5 行，就把数据行行高固定为 75 磅。好处是零编码，模板设计即可；坏处是所有行全部都是 75 磅，即使内容只有 2 个字，表格依然很空。
这个方案在两类场景下可用：导出的行数很少（比如单页单据），且内容长度有明确上限；或者使用者不介意表格松散。但凡数据是列表型、内容长度差异大，这个方案就不适合，因为表格整体观感太差。
4.2 方案 C：纯代码构建 sheet，边写边算行高
不依赖模板，完全用 POI 创建样式和数据行。这类方式的优点在于写入单元格时就能拿到文本长度，实时计算行高，不需要事后遍历。缺点是工作量大——模板里的表头样式、列宽、合并单元格、边框，全都要在代码里重建，维护成本比模板高出很多。
如果你是新项目，数据列固定、样式简单，可以选这种方式；如果你是老项目改造，有大量复杂模板，不建议迁移。我在实际项目中只对“动态列”报表用了纯代码构建，固定模板一律保留 EasyPOI 加后处理的方式。
4.3 方案对比表
| 方案 | 实现成本 | 表格观感 | 适用场景 | 风险点 |
|---|---|---|---|---|
| 模板预留高度 | 低 | 空行多，粗糙 | 内容长度上限明确、行数少 | 超长内容依旧截断 |
| 纯代码构建 | 高 | 精确 | 样式简单的动态报表 | 样式维护成本大 |
| 模板导出+后处理 | 中 | 精确 | 复杂模板+动态长文本 | 需要认真写估算逻辑 |
我最终选择方案 D（其实是建议你把“后处理”作为默认选型），理由是它不破坏模板，改动集中在导出公共层，所有使用模板导出的模块都可以直接受益。
5. 工程化落地：把行高修复封装成通用后置处理工具
5.1 工具类对外 API
为了不让每个业务代码都粘贴一遍估算逻辑，我封装了一个RowHeightAutoFitter，对外只暴露一个静态方法：
public static void fit(XSSFSheet sheet, int startRow, int endRow)参数startRow指定从哪一行开始算数据行，避免动表头；endRow指定处理到哪一行，避免全表扫描。对模板导出的场景，endRow可以直接取sheet.getLastRowNum()，但要注意列表型数据可能存在“模板尾部还有合计行、签名行”的情况，这种场景需要把合计行排除，否则合计行被撑高又难看。
5.2 完整实现：合并单元格、空行、换行符都要考虑
直接给核心代码，我在注释里写了每段为什么这么处理：
public class RowHeightAutoFitter { /** 根据经验配置的行距系数 */ private static final float LINE_HEIGHT_FACTOR = 1.5f; public static void fit(XSSFSheet sheet, int startRow, int endRow) { Map<Integer, Double> colWidthCache = new HashMap<>(); List<CellRangeAddress> mergedRegions = sheet.getMergedRegions(); for (int rowIdx = startRow; rowIdx <= endRow; rowIdx++) { XSSFRow row = sheet.getRow(rowIdx); if (row == null) { continue; } int maxLines = 1; short minCellIdx = row.getFirstCellNum(); short maxCellIdx = row.getLastCellNum(); for (int cellIdx = minCellIdx; cellIdx < maxCellIdx; cellIdx++) { XSSFCell cell = row.getCell(cellIdx); if (cell == null) { continue; } String text = getCellText(cell); if (text.isEmpty()) { continue; } double colWidthPx = getEffectiveColWidthPx(sheet, colWidthCache, mergedRegions, rowIdx, cellIdx); // 估算当前单元格按有效宽度换行后的行数 int lines = estimateLines(text, colWidthPx, cell.getCellStyle().getFontIndex()); maxLines = Math.max(maxLines, lines); } float targetHeight = maxLines * getDefaultFontHeight(row.getSheet().getWorkbook()); row.setHeightInPoints(targetHeight); } } private static String getCellText(XSSFCell cell) { if (cell.getCellType() == CellType.STRING) { return cell.getStringCellValue(); } if (cell.getCellType() == CellType.FORMULA) { try { return cell.getCellFormula(); } catch (Exception e) { return ""; } } // 数字、日期等类型按无内容处理，避免因数字误判撑高 return ""; } private static int estimateLines(String text, double colWidthPx, short fontIdx) { if (text == null || text.isEmpty()) { return 1; } double charWidthPx = 11 * 1.333; int charsPerLine = Math.max(1, (int) (colWidthPx / charWidthPx)); int lines = 1; int count = 0; for (char c : text.toCharArray()) { if (c == '\n') { lines++; count = 0; } else { count++; if (count >= charsPerLine) { lines++; count = 0; } } } return lines; } private static double getEffectiveColWidthPx(XSSFSheet sheet, Map<Integer, Double> colWidthCache, List<CellRangeAddress> mergedRegions, int rowIdx, int cellIdx) { // 如果单元格在合并区域内，有效宽度应该是整个合并区域的宽度 for (CellRangeAddress region : mergedRegions) { if (region.isInRange(rowIdx, cellIdx)) { double total = 0; for (int c = region.getFirstColumn(); c <= region.getLastColumn(); c++) { total += getColWidthPx(sheet, colWidthCache, c); } return total; } } return getColWidthPx(sheet, colWidthCache, cellIdx); } private static double getColWidthPx(XSSFSheet sheet, Map<Integer, Double> colWidthCache, int colIdx) { return colWidthCache.computeIfAbsent(colIdx, c -> (sheet.getColumnWidth(c) / 256.0) * 7.0); } private static float getDefaultFontHeight(Workbook workbook) { Font defaultFont = workbook.getFontAt(0); return defaultFont.getFontHeightInPoints() * LINE_HEIGHT_FACTOR; } }代码里我默认了 11 号字体宽度，如果你的模板大量使用 12 号或其他字号，建议把字号作为参数传入，或者直接读取单元格所在列样式字体。我这里图省事用了统一估算，但对大多数报表模板已经够用。
5.3 性能与大数据量说明
如果导出的数据行有几千上万，逐行逐格估算是可以接受的，因为只是读字符串和算行数，不涉及磁盘 IO。我实测的参考值：5 千行、12 列、单单元格文本较长的场景，完整遍历一次大约耗时 200~300ms，在导出耗时中占比非常小。真正耗时的大头是 POI 写文件本身，所以不用担心这里成为瓶颈。
有一点要注意：row.getLastCellNum()返回的是列数而不是最后一列索引，遍历时用的是< maxCellIdx，写成<=会多读一列空单元格，虽无大碍但不优雅。
5.4 使用时机：必须在workbook.write()之前调用
这是最容易踩的坑。后处理必须在workbook.write()之前调用，不是之后。因为write()的一瞬间，行高已经固化到输出流里了，之后再改内存里的 row 不会再影响已生成的字节。我最初封装时放在write()之后调用，排查了很久才发现顺序反了。
正确调用方式：
Workbook workbook = ExcelExportUtil.exportExcel(params, map); RowHeightAutoFitter.fit((XSSFSheet) workbook.getSheetAt(0), 1, ((XSSFSheet) workbook.getSheetAt(0)).getLastRowNum()); try (FileOutputStream fos = new FileOutputStream("output.xlsx")) { workbook.write(fos); }5.5 字体名称的影响
如果你的模板常用单元格是宋体或雅黑，而 POI 默认字体是 Calibri，估算出来的中文宽度会有偏差。稳妥做法是读取单元格样式的字体，再根据字体名称匹配合适的中文字宽系数。这个细节不处理，短文本看不出问题，长文本在换行临界点会偶尔差一行。我的工具类在迭代过程中就遇到了这种“偶尔差一点”的情况，最终通过读取实际Font对象解决了。
6. 避坑清单：六个容易翻车的边角场景
6.1 合并单元格会让估算宽度变小
如果备注这一列左侧或右侧还有合并单元格，getColumnWidth(cellIdx)只返回当前列的宽度，但实际可显示范围是整个合并区域。我的实现里已经考虑了这个场景：遍历 sheet 的mergedRegions，如果单元格坐标落在某个区域里，有效宽度就按区域总宽计算。不处理的话，合并区域内的长文本会被过度撑高，表格会很浪费空间。
6.2 WPS 和 Excel 对行高的重新计算行为不同
这是一个隐蔽的大坑。开发时如果用 WPS 打开文件，WPS 会在某些场景下自动重新计算行高，看起来“修好了”；但用微软 Excel 打开时，它保留文件里的固定行高，文字依旧截断。反过来也可能出现。所以验收导出效果时，必须同时用 Excel 和 WPS 各打开一次，不能只看自己常用的客户端。我从这个坑里学到的经验是：不要指望客户端做二次处理，行高必须在文件里就写对。
6.3 单元格里的换行符\n要单独计数
如果业务数据里包含换行符，比如备注里用户手动按了回车，那么即使每一行文本都不长，行数也可能很多。估算逻辑必须把\n视为强制断行，否则会严重低估行高。上面的estimateLines方法已经处理了这个边界。
6.4 表头不能参与高度重算，否则表头样式全乱
模板表头通常有固定高度、边框、背景色，如果把它也纳入估算范围，表头文字不够长时行高会被压到很矮，样式完全变味。幸好我的工具类提供了startRow参数，业务方需要自己确定表头结束的位置。如果模板结构不固定，建议在转换时同时返回“表头行号”作为参数。
6.5 Hidden 行和 Hidden 列可能影响遍历范围
有些报表会隐藏部分辅助列，但getLastRowNum()和getLastCellNum()不会跳过隐藏行/列。虽然对最终文件的行高没有破坏性影响，但会对隐藏列做无意义的计算，浪费时间。处理方式是在遍历时判断：
if (sheet.isColumnHidden(cellIdx)) { continue; }6.6 内容长度动态范围极大时，要设最大行高兜底
长文本无限撑高会带来另一个问题：一行数据可能占几百磅，整个表格一页显示不了几行，打印时分页非常难看。我的做法是设一个maxLines上限，比如超过 6 行后统一按 6 行高度展示，超出部分截断并追加省略号。这个策略属于产品层取舍，但实现时必须在估算逻辑里预留参数，否则临时改起来很麻烦。
写在最后：本质是理解 POI 不会替你算行高
这个问题的根源不在于 EasyPOI 的版本，也不在于某个参数没配好，而在于 xlsx 文件格式和 POI 的行为边界：行高是写入方必须明确给出的数值，框架不会根据文本内容自动推算。理解了这一点，你就不容易在网上各种“设置自适应行高”的帖子里浪费时间，也会明白为什么哪怕换了别的 POI 封装框架，同样的问题该出现还是会出现。
我最终留在这套方案里的核心收获有三条：一是把行高计算放到write()之前；二是估算换行要按字符宽度而不是字符串长度；三是验证环境必须同时覆盖 Excel 与 WPS。这三条看着简单，每一个都是从真实翻车现场换来的经验。如果你也在 EasyPOI 模板导出上遇到类似问题，直接照搬上面的工具类改一改参数，能省不少弯路。后续如果你们也准备把导出模块迁移到其他思路，建议先以这个后处理器为锚点，保住现有模板资产，再逐步替换底层实现，风险会小很多。
