PrimeFaces 13升级后PrimeIcons加载异常致布局错位问题排查

核心原因分析 #

PrimeFaces 11及以上版本会自动注入PrimeIcons资源，你的自定义Stylesheet/Script渲染器在处理资源URL时，可能未区分PrimeFaces自带资源与项目自定义资源，错误合并了CSS路径与字体文件路径，导致字体资源请求404，进而引发组件布局错位。

排查与解决步骤 #

1. 检查自定义渲染器的URL处理逻辑 #

• 打开自定义的StylesheetRenderer或ScriptRenderer实现类，重点查看encodeEnd方法中生成资源URL的代码。
• 确认是否存在全局路径拼接/替换逻辑（比如统一给资源URL添加前缀），这种逻辑会误修改PrimeIcons的默认路径。例如：若渲染器给所有资源URL加了/resources/css/前缀，PrimeIcons的字体路径会被错误改为/resources/css/primeicons/fonts/primeicons.woff2，导致404。
• 修复方案：针对PrimeFaces核心资源（含PrimeIcons）跳过自定义路径处理：

  @Override
  public void encodeEnd(FacesContext context, UIComponent component) throws IOException {
      Resource resource = (Resource) component.getAttributes().get("resource");
      // 跳过PrimeFaces自带资源的自定义处理
      if (resource != null && "primefaces".equals(resource.getLibraryName())) {
          super.encodeEnd(context, component);
          return;
      }
      // 仅对项目自定义CSS/JS资源应用你的路径处理逻辑
      // ... 原有自定义代码
  }
  

2. 验证PrimeIcons资源的正确路径 #

PrimeFaces 13-jakarta的PrimeIcons字体资源默认请求路径格式为：
/jakarta.faces.resource/primeicons/fonts/primeicons.woff2.xhtml?ln=primefaces
直接在浏览器访问该路径（替换为你的域名），若能返回字体文件，说明资源本身存在，问题出在URL生成逻辑。

3. 临时禁用PrimeIcons自动注入（应急方案） #

若暂时无法修复渲染器，可在web.xml中添加参数禁用自动注入，避免加载错误资源：

<context-param>
    <param-name>primefaces.PRIMEICONS_ENABLED</param-name>
    <param-value>false</param-value>
</context-param>

注意：禁用后PrimeFaces组件的图标可能无法正常显示，仅作为临时过渡方案，优先修复渲染器逻辑。

4. 排查依赖冲突 #

• 检查项目依赖，确认未重复引入primeicons jar包（PrimeFaces 13-jakarta已内置PrimeIcons）。
• 若使用Maven，可通过依赖树排查并排除多余依赖：

  <dependency>
      <groupId>org.primefaces</groupId>
      <artifactId>primefaces</artifactId>
      <version>13.0.6-jakarta</version>
      <exclusions>
          <exclusion>
              <groupId>org.primefaces</groupId>
              <artifactId>primeicons</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

• 若手动引入过PrimeIcons依赖，直接移除该依赖项。

5. 清理缓存并重启服务 #

• 清空浏览器缓存，避免旧的错误路径被缓存。
• 清理GlassFish服务器临时目录（通常位于glassfish/domains/你的域/下的tmp或cache文件夹），重启服务器确保新配置生效。

内容的提问来源于stack exchange，提问作者RacoonMaster