迁移至TomEE Plus 10.1的Jakarta EE Maven项目CSS资源404求助

项目背景 #

该项目历经三次迁移：

• TomEE 1.7 → TomEE 7.0
• TomEE 7.0 → TomEE 9.1.0
• TomEE 9.1.0 → TomEE 10.1.1
  早年复制粘贴的代码可能遗留配置问题。

已尝试操作 #

• 将src/main/webapp/resources移至src/main/resources
• 移除<h:outputStylesheet name="/default/css/tooltip.css" />中name属性的前导/

当前现象 #

浏览器控制台所有资源请求返回404，请求路径被自动追加.xhtml，虚拟路径jakarta.faces.resource未正确映射到资源目录，示例请求：

GET welcome.xhtml  https://localhost:8443/Test/jakarta.faces.resource/default/css/tooltip.css.xhtml net::ERR_ABORTED 404 (Not Found)

相关配置与结构 #

资源引入方式 #

CSS通过welcome.xhtml的模板main.xhtml引入：

<h:outputStylesheet name="/default/css/tooltip.css" />

项目结构 #

src -
-- main
    -- java
    -- webapp
      -- WEB-INF
        -- templates
          -- main.xhtml
         web.xml
         beans.xml
     -- resources
       -- default 
         -- css
             tooltip.css
         -- images

web.xml配置 #

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xmlns="https://jakarta.ee/xml/ns/jakartaee" 
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd" 
         id="WebApp_ID" version="6.0">
  <servlet>
    <servlet-name>facesServlet</servlet-name>
    <servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>facesServlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
    <servlet-name>facesServlet</servlet-name>
    <url-pattern>/jakarta.faces.resource/*</url-pattern>
  </servlet-mapping>
  <context-param>
    <param-name>jakarta.faces.WEBAPP_RESOURCES_DIRECTORY</param-name>
    <param-value>/resources</param-value>
  </context-param>
</web-app>

beans.xml配置 #

<?xml version="1.0" encoding="UTF-8"?>
<beans 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/beans_4_0.xsd"
       version="4.0" bean-discovery-mode="annotated">
</beans>

pom.xml核心配置 #

<project 
   xmlns="http://maven.apache.org/POM/4.0.0" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>Test</groupId>
 <artifactId>Test</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <packaging>war</packaging>
 <dependencies>
   <dependency>
      <groupId>jakarta.platform</groupId>
      <artifactId>jakarta.jakartaee-api</artifactId>
      <version>10.0.0</version>
      <scope>provided</scope>
   </dependency> 
  <dependency>
      <groupId>org.glassfish</groupId>
      <artifactId>jakarta.faces</artifactId>
      <version>4.1.3</version>
      <scope>provided</scope>
  </dependency>
 </dependencies>
 <build>
  <plugins>
    <plugin>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.4.0</version>
    </plugin>
    <plugin>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.13.0</version>
      <configuration>
        <release>22</release>
      </configuration>
    </plugin>
  </plugins>
 </build>
</project>

问题排查与修复方案 #

1. 资源目录位置错误 #

JSF的Web资源目录必须放在src/main/webapp下，src/main/resources是Java类路径资源目录，编译后会进入WEB-INF/classes，JSF默认不会从这里加载前端资源。

修复：
将src/main/resources/default目录整体移动到src/main/webapp/resources下，最终结构应为：

src -
-- main
    -- java
    -- webapp
      -- resources
        -- default 
          -- css
              tooltip.css
          -- images
      -- WEB-INF
        -- templates
          -- main.xhtml
         web.xml
         beans.xml

2. h:outputStylesheet属性错误 #

name属性前导/会被视为绝对路径，而JSF资源解析基于webapp/resources根目录，需去掉前导斜杠：

修复：
修改资源引入代码为：

<h:outputStylesheet name="default/css/tooltip.css" />

3. 移除冗余的资源目录配置 #

jakarta.faces.WEBAPP_RESOURCES_DIRECTORY的默认值就是/resources，当前配置属于冗余，反而可能引发路径解析冲突，建议删除：

修复：
移除web.xml中的以下配置段：

<context-param>
  <param-name>jakarta.faces.WEBAPP_RESOURCES_DIRECTORY</param-name>
  <param-value>/resources</param-value>
</context-param>

4. 验证Maven打包结果 #

执行mvn clean package后，解压生成的war包，确认resources/default/css/tooltip.css存在于war包根目录下，确保资源被正确打包。

验证步骤 #

1. 按上述修改调整目录与代码
2. 重新打包部署项目
3. 启动TomEE后查看浏览器控制台，资源请求路径应变为：

   https://localhost:8443/Test/jakarta.faces.resource/default/css/tooltip.css?ln=default
   

   不再带有.xhtml后缀，且返回200状态码。

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