Apache POI 踩坑：setFontFamily 二次设置字体不生效、样式残留问题深度解析

Apache POI 踩坑：setFontFamily 二次设置字体不生效、样式残留问题深度解析

日常使用Apache POI 生成、编辑 Word 文档（.docx）时，很多开发者都会遇到一个诡异的字体样式问题：

同一个 XWPFRun 段落，第一次调用 setFontFamily 设置字体完全正常，第二次重新设置字体时，字体样式不生效，文档样式残留旧配置，导致最终排版错乱。

这并不是代码写法问题，而是 POI 底层 setFontFamily 方法的隐性设计缺陷（Bug 级行为）。本文将深度拆解源码、分析根因，并提供两种稳定可靠的终极解决方案。

---

一、问题现象：诡异的字体覆盖失效

1. 复现场景

对同一个 Word 文本片段XWPFRun 进行两次字体设置操作：

• 第一次设置字体：例如设置字体为「微软雅黑」

• 第二次覆盖设置：例如修改字体为「宋体」

2. 实际结果

• 第一次设置：Word 底层 XML 中 ascii / hAnsi / cs / eastAsia四个字体字段全部同步更新，文档字体正常

• 第二次设置：仅 ascii（英文字体）被修改，中文、东亚文字、特殊字符字体完全不变

• 最终效果：文档中英文变新字体，中文依旧是旧字体，整体样式错乱，二次设置失效

3. 核心特征

字体样式首次赋值全量生效，二次赋值局部失效，无报错、无异常，极难排查。

---

二、底层源码溯源：为什么会出现这个问题？

我们直接看 POI 核心源码 XWPFRun.setFontFamily 的底层逻辑，问题根源一目了然。

1. 核心源码逻辑

单参数设置字体的方法，本质是调用空规则的重载方法：

public void setFontFamily(String fontFamily) {
    setFontFamily(fontFamily, null);
}

真正的核心实现：

public void setFontFamily(String fontFamily, FontCharRange fcr) {
    CTRPr pr = this.getRunProperties(true);
    CTFonts fonts = pr.sizeOfRFontsArray() > 0 ? pr.getRFontsArray(0) : pr.addNewRFonts();
    
    if (fcr == null) {
        fonts.setAscii(fontFamily);
        // 关键：仅【未赋值】时才会设置，一旦赋值永久不再覆盖
        if (!fonts.isSetHAnsi()) {
            fonts.setHAnsi(fontFamily);
        }
        if (!fonts.isSetCs()) {
            fonts.setCs(fontFamily);
        }
        if (!fonts.isSetEastAsia()) {
            fonts.setEastAsia(fontFamily);
        }
    } else {
        // 按指定字符范围单独赋值
        switch (fcr) {
            case ascii: fonts.setAscii(fontFamily); break;
            case hAnsi: fonts.setHAnsi(fontFamily); break;
            case cs: fonts.setCs(fontFamily); break;
            case eastAsia: fonts.setEastAsia(fontFamily); break;
        }
    }
}

2. 逐次执行逻辑拆解

✅ 第一次设置字体（全新 Run）

首次调用时，Run 无任何字体配置，会新建空白 CTFonts 对象：

• hAnsi / cs / eastAsia 状态均为 未设置（unset）

• 所有 isSetXXX() 判断均为 false

• 最终 四个字体字段全部赋值，中英文、特殊字符字体统一

❌ 第二次设置字体（复用旧 Run）

二次调用时，会复用第一次生成的 CTFonts 对象：

• hAnsi / cs / eastAsia 已被标记为 已设置（isSet=true）

• 三个分支判断全部不执行，跳过赋值

• 仅执行 fonts.setAscii(fontFamily)，只修改英文字体

• 中文字体（eastAsia）、特殊字符字体永久残留旧值

3. Bug 本质总结

POI 的单参数 setFontFamily 是一次性赋值逻辑：

所有字体字段仅首次空白状态时自动全量填充，一旦赋值过，后续永久不再自动覆盖，只会修改 ASCII 英文字体。

这是典型的 API 设计缺陷，并非使用者代码错误。

---

三、Word 字体四个字段含义（必懂）

Word 文档字体分为四个字符区间，覆盖所有文本场景，这也是中文失效的核心原因：

• ascii：纯英文、数字、基础符号

• hAnsi：西欧语言字符

• cs：复杂脚本字符（阿拉伯语、希伯来语等）

• eastAsia ：东亚文字（中文、日文、韩文）

二次设置仅修改 ascii，中文依赖 eastAsia 旧值，所以中文字体永远不生效。

---

四、两种完美解决方案（可直接商用）

针对该 Bug，提供两种零坑、全覆盖的解决方案，彻底解决二次字体不生效问题。

方案一：指定字符范围，强制全量覆盖（简洁推荐）

不使用单参数方法，手动给四个字符区间逐一赋值，无视 POI 的判断逻辑，强制统一字体。

/**
 * 强制统一设置Run字体（修复POI二次设置不生效Bug）
 * @param run 文本段落
 * @param fontFamily 字体名称
 */
public static void setFullFontFamily(XWPFRun run, String fontFamily) {
    // 全覆盖：英文、西欧、复杂脚本、东亚中文 全部强制刷新
    run.setFontFamily(fontFamily, FontCharRange.ascii);
    run.setFontFamily(fontFamily, FontCharRange.hAnsi);
    run.setFontFamily(fontFamily, FontCharRange.cs);
    run.setFontFamily(fontFamily, FontCharRange.eastAsia);
}

优点：代码简洁、无冗余、性能高，适合绝大多数业务场景。

方案二：清空旧字体配置，重建全新字体（彻底重置）

先删除原有所有字体配置，再新建字体对象并全量赋值，彻底杜绝样式残留。

/**
 * 清空旧字体并重置（彻底解决字体残留问题）
 * @param run 文本段落
 * @param fontFamily 字体名称
 */
public static void resetFontFamily(XWPFRun run, String fontFamily) {
    CTRPr rPr = run.getCTR().isSetRPr() ? run.getCTR().getRPr() : run.getCTR().addNewRPr();
    // 清空历史字体配置
    rPr.unsetRFonts();
    // 新建字体配置并全量赋值
    CTFonts fonts = rPr.addNewRFonts();
    fonts.setAscii(fontFamily);
    fonts.setHAnsi(fontFamily);
    fonts.setCs(fontFamily);
    fonts.setEastAsia(fontFamily);
}

优点：完全重置样式，无任何残留，适合需要频繁切换字体、复杂排版场景。

---

五、实战避坑总结

1. 禁止使用单参数 setFontFamily 做动态、多次字体修改，仅可用于首次初始化

2. 中文字体不生效，90% 都是 eastAsia 字段未刷新 导致

3. POI 该 API 属于隐性坑，无报错、难排查，优先使用封装后的全量赋值工具方法

4. 所有动态修改 Word 字体的场景，必须覆盖 四个字符区间，才能保证中英文样式统一

---