Quarkus 3.6.4中Freemarker Template Not Found异常求助

问题场景 #

配置Quarkus 3.6.4应用集成Freemarker后，执行mvnw quarkus:dev启动服务，访问/hello?name=max时抛出模板找不到的异常。

错误日志 #

2024-01-12 10:02:11,412 ERROR [io.qua.ver.htt.run.QuarkusErrorHandler] (executor-thread-1) HTTP Request to /hello?name=max failed, error id: 1dac2036-f070-415a-9ef4-cad4ebfdbed7-1: java.lang.RuntimeException: Error injecting freemarker.template.Template org.acme.HelloResource.hello
        at org.acme.HelloResource_Bean.doCreate(Unknown Source)
        at org.acme.HelloResource_Bean.create(Unknown Source)
        at org.acme.HelloResource_Bean.create(Unknown Source)
        at io.quarkus.arc.impl.AbstractSharedContext.createInstanceHandle(AbstractSharedContext.java:117)
        at io.quarkus.arc.impl.AbstractSharedContext$1.get(AbstractSharedContext.java:41)
        at io.quarkus.arc.impl.AbstractSharedContext$1.get(AbstractSharedContext.java:38)
        at io.quarkus.arc.impl.LazyValue.get(LazyValue.java:32)
        at io.quarkus.arc.impl.ComputingCache.computeIfAbsent(ComputingCache.java:69)
        at ...
Caused by: jakarta.enterprise.inject.CreationException: freemarker.template.TemplateNotFoundException: Template not found for name "hello.ftl".
The name was interpreted by this TemplateLoader: MultiTemplateLoader(loader1 = ClassTemplateLoader(classLoader="QuarkusClassLoader:Quarkus Runtime ClassLoader: DEV for caronte-1.0.0-SNAPSHOT restart no:0@6de0f580", basePackagePath="freemarker/templates/")).
        at io.quarkiverse.freemarker.runtime.FreemarkerTemplateProducer_ProducerMethod_getTemplate_l8tBZCOFgJ9DySmRlLH9CkgP6Lw_Bean.create(Unknown Source)
        at io.quarkiverse.freemarker.runtime.FreemarkerTemplateProducer_ProducerMethod_getTemplate_l8tBZCOFgJ9DySmRlLH9CkgP6Lw_Bean.get(Unknown Source)
        at io.quarkiverse.freemarker.runtime.FreemarkerTemplateProducer_ProducerMethod_getTemplate_l8tBZCOFgJ9DySmRlLH9CkgP6Lw_Bean.get(Unknown Source)
        at io.quarkus.arc.impl.CurrentInjectionPointProvider.get(CurrentInjectionPointProvider.java:48)
        ... 29 more
Caused by: freemarker.template.TemplateNotFoundException: Template not found for name "hello.ftl".
The name was interpreted by this TemplateLoader: MultiTemplateLoader(loader1 = ClassTemplateLoader(classLoader="QuarkusClassLoader:Quarkus Runtime ClassLoader: DEV for xxx-1.0.0-SNAPSHOT restart no:0@6de0f580", basePackagePath="freemarker/templates/")).
        at freemarker.template.Configuration.getTemplate(Configuration.java:2957)
        at freemarker.template.Configuration.getTemplate(Configuration.java:2759)

pom.xml关键配置 #

...
  <properties>
    <compiler-plugin.version>3.11.0</compiler-plugin.version>
    <maven.compiler.release>21</maven.compiler.release>
    <quarkus.platform.version>3.6.4</quarkus.platform.version>
    <skipITs>true</skipITs>
    <surefire-plugin.version>3.1.2</surefire-plugin.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy-reactive</artifactId>
    </dependency>
    <dependency>
      <groupId>io.quarkiverse.freemarker</groupId>
      <artifactId>quarkus-freemarker</artifactId>
      <version>1.0.0</version>
    </dependency>
    ...
  </dependencies>
 ...

控制器代码 #

@Path("hello")
public class HelloResource {
    @Inject
    @TemplatePath("hello.ftl")
    Template hello;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello(@QueryParam("name") String name) throws IOException, TemplateException {
        StringWriter stringWriter = new StringWriter();
        hello.process(Map.of("name", name), stringWriter);
        return stringWriter.toString();
    }
}

模板文件信息 #

• 路径：/src/main/resources/freemarker/templates/hello.ftl
• 内容：

Hello ${name}!

解决方案 #

1. 修复依赖版本兼容性 #

quarkus-freemarker 1.0.0仅适配Quarkus 2.x版本，Quarkus 3.x需要使用2.x系列的依赖版本。修改pom.xml中的freemarker依赖：

<dependency>
  <groupId>io.quarkiverse.freemarker</groupId>
  <artifactId>quarkus-freemarker</artifactId>
  <version>2.0.0</version>
</dependency>

更规范的做法是通过Quarkus平台BOM管理依赖版本，避免手动指定版本时出现兼容性问题。

2. 验证模板路径与文件名 #

确保模板文件确实存在于src/main/resources/freemarker/templates/目录下，且文件名（包括大小写）与@TemplatePath注解中的完全一致（Linux/macOS系统区分文件名大小写）。

3. 清理并重新构建 #

执行以下命令清理旧构建产物，再启动开发模式：

mvnw clean install
mvnw quarkus:dev

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