Jakarta EE10+Wildfly27自定义Facelets标签启动配置报错

以下是针对该异常的排查和解决步骤：

1. 检查标签库XML文件的语法与命名空间 #

apollo.taglib.xml的语法错误或命名空间不匹配是最常见的原因，需确保符合Jakarta EE 10规范：

<?xml version="1.0" encoding="UTF-8"?>
<facelet-taglib xmlns="https://jakarta.ee/xml/ns/jakartaee"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-facelettaglibrary_4_0.xsd"
                version="4.0">
    <namespace>http://your-domain.com/apollo</namespace>
    <tag>
        <tag-name>hbox</tag-name>
        <source>/WEB-INF/tags/hbox.xhtml</source>
    </tag>
    <tag>
        <tag-name>vbox</tag-name>
        <source>/WEB-INF/tags/vbox.xhtml</source>
    </tag>
</facelet-taglib>

• 必须使用Jakarta EE 10的命名空间https://jakarta.ee/xml/ns/jakartaee，不能沿用旧的Java EE命名空间
• version需设为4.0，对应Jakarta Faces 4规范
• 检查标签闭合、属性拼写等基础语法错误

2. 验证web.xml中的配置参数 #

确保context-param的参数名和路径正确，注意Jakarta EE 10已将前缀从javax改为jakarta：

<context-param>
    <param-name>jakarta.faces.FACELETS_LIBRARIES</param-name>
    <param-value>/WEB-INF/apollo.taglib.xml</param-value>
</context-param>

• 不要使用旧的javax.faces.FACELETS_LIBRARIES参数名
• 确认param-value中的文件路径与实际文件位置完全一致

3. 检查自定义标签文件的路径与内容 #

• 确认hbox.xhtml和vbox.xhtml确实存放在WEB-INF/tags目录下，Linux环境下需注意文件名大小写匹配
• 标签文件需用<ui:composition>包裹内容，不能包含完整的HTML结构（如<html>、<body>），示例：

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:ui="jakarta.faces.facelets"
                xmlns:h="jakarta.faces.html">
    <div style="display: flex; flex-direction: row;">
        <ui:insert />
    </div>
</ui:composition>

4. 清理缓存并重新部署 #

• 删除Wildfly的standalone/data和standalone/tmp目录下的缓存文件，避免旧配置残留
• 重新打包部署应用，确保所有文件正确复制到部署包中

5. 排除依赖冲突 #

Wildfly 27自带Jakarta Faces 4.0，不要在项目的pom.xml或build.gradle中额外引入Jakarta Faces依赖，避免版本冲突导致加载异常

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