VelocityEngine未加载默认布局模板问题排查（Spring Boot环境）

首先明确：你之前配置的tools.view.servlet.layout是Velocity Tools为Web MVC场景设计的参数，直接用VelocityEngine渲染邮件时这套配置不会生效，因为邮件渲染是通过API直接调用模板引擎，不走Servlet视图解析流程。

下面是两种可行的解决方案：

方案一：用#parse指令手动实现布局 #

这种方式简单直接，不需要额外工具类：

1. 修改布局模板base.vm，添加业务模板的占位逻辑：

<!DOCTYPE html>
<html>
<head>
    <title>$emailTitle</title>
    <style>/* 通用样式 */</style>
</head>
<body>
    <div class="mail-header">系统通知</div>
    <!-- 加载业务模板内容 -->
    #parse($businessTemplatePath)
    <div class="mail-footer">如有疑问请联系客服</div>
</body>
</html>

2. 在Java代码中，将业务模板的路径作为参数传入，渲染布局模板：

// 初始化VelocityEngine（确保已配置正确的资源加载路径）
VelocityEngine velocityEngine = new VelocityEngine();
velocityEngine.setProperty(RuntimeConstants.RESOURCE_LOADER, "classpath");
velocityEngine.setProperty("classpath.resource.loader.class", ClasspathResourceLoader.class.getName());
velocityEngine.init();

// 构造模板参数
Map<String, Object> model = new HashMap<>();
model.put("emailTitle", "订单支付成功通知");
model.put("businessTemplatePath", "templates/order-success.vm"); // 业务模板的类路径

// 渲染布局模板
String finalMailContent = VelocityEngineUtils.mergeTemplateIntoString(
    velocityEngine,
    "templates/base.vm", // 布局模板路径
    StandardCharsets.UTF_8.name(),
    model
);

方案二：用Velocity Tools的LayoutTool处理布局 #

如果你想保留布局与业务模板的分离逻辑，可以借助velocity-tools-generic中的LayoutTool：

1. 修改base.vm，用$content作为业务内容的占位符：

<!DOCTYPE html>
<html>
<head>
    <title>$emailTitle</title>
</head>
<body>
    <div class="header">系统通知</div>
    <!-- 业务模板渲染后的内容 -->
    $content
    <div class="footer">© 2024 系统团队</div>
</body>
</html>

2. 在Java代码中先渲染业务模板，再用布局模板包裹：

// 先渲染业务模板
String businessContent = VelocityEngineUtils.mergeTemplateIntoString(
    velocityEngine,
    "templates/order-success.vm",
    StandardCharsets.UTF_8.name(),
    model
);

// 构造布局参数，传入业务内容
Map<String, Object> layoutModel = new HashMap<>(model);
layoutModel.put("content", businessContent);

// 渲染布局模板
String finalMailContent = VelocityEngineUtils.mergeTemplateIntoString(
    velocityEngine,
    "templates/base.vm",
    StandardCharsets.UTF_8.name(),
    layoutModel
);

注：如果需要动态切换布局，可以用LayoutTool的setLayout方法指定不同的布局模板路径。

关于是否改用macros #

macros更适合复用小粒度的通用组件（比如按钮、日期格式化、重复的表格行），而布局是整体页面结构，用上面两种方法更合适。如果你的布局里包含重复的小组件，可以结合macros一起使用，但不需要为了布局而改用macros。

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