velocity-subtemplate-variable-fix
为什么你的 Velocity 子模板变量总是失效？一行代码解决了
阅读前提：你正在用 Velocity 做模板引擎开发，主模板能正常渲染，但子模板里一用变量就报空指针或者路径找不到。
先说我的血泪史
昨晚被一个问题折磨了两个小时：
主模板引用子模板#parse("$!relPath/S01/S0101.vm")，子模板里我想引用公共宏#parse("$!relPath/common/macro.vm")——结果运行时子模板里$!relPath直接变成空字符串，文件找不到，页面崩了。
我第一反应是：是不是变量名写错了？
检查了十几遍，没毛病。
又怀疑：是不是 Velocity 版本问题？
换了个版本，问题依旧。
最后发现真相的时候，我只想翻白眼 ——
Velocity 的 #parse 根本不会自动把主模板的变量传递给子模板。
问题根因
Velocity 的#parse和#include有一个非常反直觉的设计：
子模板是独立执行的，它不会继承主模板中的变量上下文。
也就是说，你在主模板里#set($!relPath = "templates/tdt")，子模板里$!relPath依然是null。
这和大多数人的预期完全相反。
解决方案
在 Java 代码里往 context 中塞变量，而不是在模板里 set：
// TdtEntQueryServiceImpl.javapublicStringrenderTemplate(...){// 省略其他代码...// 设置模板路径前缀，用于子模板引用StringrelPath=TEMPLATE_FILE.substring(0,TEMPLATE_FILE.lastIndexOf("/"));context.put("relPath",relPath);// 继续正常渲染...}主模板里直接用：
#parse("$!relPath/$!section.categoryCode/$!subSection.productCode.vm")子模板里也能正常拿到$!relPath了。
为什么在代码里 set 而不是模板里 set
| 方式 | 子模板能拿到吗 | 推荐度 |
|---|---|---|
主模板#set($!relPath = "xxx") | ❌ 不能 | ⭐ |
Java 代码context.put("relPath", ...) | ✅ 可以 | ⭐⭐⭐⭐⭐ |
核心原因：#set只在当前模板作用域生效，#parse引入的子模板是全新的上下文。
扩展：公共宏文件也得用完整路径
公共宏文件同理，必须在子模板里写完整路径：
#parse("$!relPath/common/macro.vm")经验总结
- Velocity 的变量作用域比想象中更隔离——不要假设子模板能看到主模板的上下文
- 跨模板共享变量，扔到 context 里——这是唯一靠谱的方式
- #parse 和 #include 是两回事——前者解析执行模板，后者只做文件引入，不会解析变量
踩坑提示
如果你正在用 Velocity 做报告生成或者类似的模板渲染，遇到了子模板变量失效的问题，先检查：
- 变量是在 Java 代码的 context 里 set 的，还是在主模板里 #set 的？
- 子模板里引用的路径是不是完整路径？
- 确认用的是 #parse 而不是 #include？
希望这篇文章能帮你少走两个小时弯路。
你有遇到过类似的模板引擎坑吗？欢迎留言交流 👇