1. 问题全貌一个典型的模板渲染“玄学”现场先说说我这次遇到的场景。项目是一个老牌的 Java Web 服务页面渲染用的是 Apache Velocity 模板引擎。这个引擎虽然现在用的人少了点但存量项目里依然有大量业务跑在它上面尤其是报表类、邮件通知类、代码生成器这类偏“文本生成”的场景。任务描述很清晰在批量生成月度报表邮件时邮件正文的结构是固定的——页头、正文、页脚其中页头里包含用户昵称、头像、月度积分汇总正文里是几段动态生成的业务数据。设计上把它们拆成了多个子模板通过#parse指令组合。结果一跑上线用户收到的邮件里页头和正文里的几个变量值全成了空字符串。而单独解析这套子模板时又一切正常变量都能正确渲染。项目标题里的 “velocity-subtemplate-variable-fix” 指的就是这个坑——在 Velocity 子模板嵌套场景下变量无法正确解析或访问不到的修复过程。这类问题在 Velocity 相关的脚本渲染、页面模板、代码生成等场景里其实非常常见但网上资料普遍只讲到“父模板变量传不进去”这一层真正代码层面的执行机制、作用域规则、排查手段往往没人说透。先说结论Velocity 并不是 JSP 那种“每个文件独立编译、独立变量查找”的模型它的变量查找顺序、子模板对父模板变量的可见性、#set指令的生效位置都和很多人的直觉不一样。搞清楚这套底层机制再回头排查整个问题就明朗了。适合谁看团队里还在维护 Velocity 模板项目的开发、做邮件/报表模板渲染的工程师以及准备从其他模板引擎迁移到 Velocity 或做技术交接的人。这篇文章不绕弯子直接讲底层机制、踩坑过程和可复现的修复方案。2. 先把 Velocity 的子模板机制彻底讲透2.1 两个入口指令的本质区别Velocity 里加载子模板有两个指令#include和#parse。很多人把它们混着用但两者的执行语义完全不同这是很多悲剧的根源。#include的行为是把子模板文件的内容当成纯文本直接插入到当前模板的输出流中完全不经过解析引擎。也就是说子模板文件里哪怕写了一堆$userName引擎也不会去解析它$userName会原样打印出来。它适合的场景是引入一段静态文本比如版权声明、协议条款不需要动态渲染。#parse则不同它是让子模板作为独立的模板单元走完整的解析和渲染流程。子模板里的$引用会被引擎正常解析变量从当前上下文中查找。子模板渲染完后的输出插入到父模板调用#parse的位置。我这次同事就是误用了#include他把页头模板里的变量拒之门外了。这是第一层问题也是最容易自查到的。但即便用了#parse也不代表万事大吉。因为#parse会引入新的变量作用域问题而且#parse的路径解析方式也和#include不同——#parse默认基于当前模板所在目录来查找相对路径#include则基本是相对于根路径。多级嵌套时路径写错了也显示不出来但这种报错通常是“找不到模板”的运行时错误比较容易察觉。2.2 子模板对父模板变量的可见性规则这是整个问题最核心的部分。很多从 JSP 或 FreeMarker 转过来的开发者默认认为“子模板是一个独立上下文父模板的变量需要显式传入”但这在 Velocity 里是不准确的。Velocity 的Context是一个全局性的变量容器。模板解析时所有通过context.put(key, value)注入的数据在整个渲染链路的任何地方都可以直接访问无论你嵌套多少个#parse。比如你有一个velocityContext放了userName在main.vm里#parse(header.vm)header.vm里面写$userName它直接就能取到不需要任何额外传递。这就是 Velocity 子模板变量机制的底层规则子模板可以读取父模板以及全局 Context 中的所有变量。那问题来了既然能读到为什么还会为空这就要提到第二个隐藏规则子模板里通过#set创建的变量默认情况下不会反向影响父模板上下文并且它的生命周期仅限于当前模板渲染单元的本地作用域。举个最容易踩坑的例子#set($msg outer) #parse(child.vm) after parse, msg $msg而child.vm的内容是#set($msg inner) child sees msg $msg你可能以为执行结果里msg已经被改成inner了但实际上在after parse那一行$msg输出的可能是outer也可能是inner取决于你的 Velocity 版本以及#parse指令的封装方式非常玄学。我遇到的情况就是我在header.vm里通过#set临时构造了一些变量比如把日期格式化后的字符串赋值给一个临时变量结果父模板后面引用这个临时变量时就是空。这里要分清楚“读取”和“写入”的差异。读取是全局可见的写入则受限于局部作用域。Velocity 官方文档里对#set的说明是“变量赋值基于当前上下文”但实际执行时#parse加载的子模板往往运行在一个独立的Context包装层里这个包装层负责局部变量的隔离。再往下挖一层Velocity 1.7 之前和 1.7 之后的行为有细微差别。当子模板里对已有变量执行#set覆盖时旧版本会直接改掉上下文里的值新版本则倾向于只在局部遮蔽。如果你的项目里混用了不同版本的 Velocity 依赖那同一个模板在不同环境里跑出的结果都可能不一样。所以千万不要在子模板里依赖“修改父模板变量”这种副作用。3. 三类导致变量失效的深层原因解析3.1 变量名拼写和引用类型不一致这个原因听起来蠢但在我排查过程中占据了不小的比例。Velocity 是弱类型语言变量名其实就是字符串 key。你在后台 Java 代码里context.put(userName, 张三)但模板里写的是$username或$user_name引擎查不到就直接输出空字符串了。它不会报错不会警告连日志里都不会有任何提示特别隐蔽。还有一种是引用类型问题。Velocity 的对象属性访问有几种写法$user.name、$user.getName()、$user.Name。前两者等价但如果你后台放的是Map那么$user.name的行为取决于Map.get(name)是否有值如果是 JavaBean那必须有对应的getName()方法。此外$user.Name这种写法Velocity 会先尝试找getName()方法找不到再尝试get(Name)都找不到就返回空。在子模板里这种失败会静默发生最终体现就是变量空白。另外一个容易忽略的是变量类型为 null 的情况。后台代码确实把 key 放进 context 了但 value 是 null模板里直接$user.name输出为空。再加一个典型场景后台放的是字符串null模板里看到的是字符串 “null” 而你以为它是空值两个排查方向完全不同。我的建议是写一个统一的后台调试辅助类在渲染前遍历 context 里所有 key-value把 null 值和字符串 null 值单独打日志。这样能过滤掉大量“假变量失效”问题。3.2 模板加载顺序与#set位置问题Velocity 模板渲染是从上到下逐步执行的。也就是说#set指令只有在它被执行到之后变量才会被赋值如果变量在#set之前就被引用了你拿到的就是空值。放在子模板场景里很容易出现这种情况#parse(header.vm) #set($title Main Title) div${title}/div如果header.vm里面引用了$title而$title是在#parse之后才被#set的那么header.vm里的$title就是空的。这种错误在单模板文件里很好发现但在多文件嵌套时你需要像读代码一样在脑子里过执行顺序很多人会下意识认为“所有变量在渲染前都已经准备好了”其实不是。特别要注意#foreach和#if等指令块的内部#set作用域。比如#foreach($item in $items) #set($total $item.price) #end total $total循环结束后$total的值是最后一次循环赋的值如果列表为空则$total永远是未定义的。子模板里如果恰好用了这种循环内变量循环一空就全盘崩溃。顺带提一个 Velocity 版本的细节Velocity 1.7 增加了#break指令如果你用的是老版本循环里的中断逻辑需要靠#if包裹这也会导致变量赋值的路径分支增多排查时要格外小心。我个人在写模板时养成了一个习惯所有用于输出的变量要么在最顶部一个集中区域进行赋值要么确保它一定来自全局 Context绝不依赖嵌套子模板里的赋值。这样的模板读起来清晰排查起来也省心。3.3 模板缓存导致更新不生效的“假修复”还有一个常见的坑你修改了子模板文件但页面输出还是老样子你以为是变量问题来回改 Java 代码结果根本不是。Velocity 默认使用FileResourceLoader加载模板文件并且开启了缓存机制。这个缓存的时间间隔由file.resource.loader.modificationCheckInterval控制单位是秒。默认值是 -1意味着永不检查文件是否更新。在开发环境你可能在 velocity.properties 里配置了 60 秒的检查间隔但生产环境如果没配置意味着模板文件一旦被加载就永远使用内存中的缓存版本。这时候就会出现“模板里变量改了半天没用”的错觉。解决办法是在配置里设置一个合理的改动检查间隔比如file.resource.loader.modificationCheckInterval 5但这个方法有性能损耗每次渲染前文件系统都会做一次时间戳比对。对高并发场景不友好。我的建议是开发环境打开热加载生产环境要么配合发布系统在发版时强制刷新缓存要么用 Spring 的VelocityEngineFactoryBean明确管理缓存生命周期。这里得明确一点模板缓存问题的本质是你看到的内容和磁盘上的模板内容不一致这和变量解析失败的外在表现几乎一样——都是输出不对但原因完全不在同一个维度。排查时务必先确认当前程序到底用的是哪个版本的模板。4. 修复方案与实操回顾4.1 从日志到复现完整排查路径我的排查过程是这样的可以在遇到类似问题时直接套用第一步确认变量到底有没有进入 Context。在渲染入口处加一段临时日志打印所有 key-valuefor (Object key : context.getKeys()) { System.out.println(key: key , value: context.get(key)); }如果这里就发现 key 不存在那问题在后台 Java 代码——检查拼写、检查是否把 value 放在另一个 context 里了。第二步如果 key 存在但输出的模板里还是空就要区分是解析路径问题还是变量引用问题。在子模板开头加一行调试输出!-- DEBUG subtemplate started -- $userName !-- DEBUG subtemplate ended --放到页面上看这行注释有没有出现。没出现说明子模板压根没被加载或路径错误出现了但$userName是空的才进入下一步。第三步用一个最小的模板复现。我把整个邮件模板简化成只有main.vm和child.vm两个文件main.vm:#set($userName test-user) start main #parse(child.vm) end mainchild.vm:start child username $userName end child然后分别用Velocity.mergeTemplate和原项目里的VelocityEngine去跑同一份模板对比输出。这个方法能快速定位是引擎配置问题还是模板逻辑问题。我跑下来的现象是用我们项目里封装的VelocityEngine跑child.vm里的$userName为空直接裸跑Velocity静态类一切正常。这基本就锁定了问题出在项目封装层。4.2 真正的元凶子模板渲染用的独立 ChainedContext定位到封装层后我看了代码发现项目里对#parse的二次封装里有这么一层逻辑给每次子模板渲染都包了一个新的ChainedContext把原始 Context 作为它的 parent。理论上这层封装是为了让子模板能读父变量通过 parent 链但实际执行时Velocity 在处理#parse的时候会对传入的 Context 做内部包装——#parse指令内部会基于当前 Context 再创建一个上下文给子模板用确保局部变量不互相污染。这个设计本意是好的问题出在角色分配上父模板里如果通过#set修改变量值子模板里读到的还是旧值。而我的模板里偏偏在header.vm里#set了几个格式化变量父模板后面的内容又想用这些变量。由于它们被“隔离”在了子模板的内部上下文里父模板自然读不到。那为什么裸跑没问题因为裸跑时#parse的子模板上下文和父模板上下文是同一个对象#set的修改能直接反映到父模板中。不同封装方式导致行为不一致。修复有两种方向方向一模板侧修改。改掉在子模板里用#set输出中间变量的坏习惯把需要传给父模板后段使用的变量放到渲染入口处提前设置好或者让这些变量直接引用全局 Context 的数据不经过子模板中转。方向二Java 侧修改。如果你的模板封装层确实存在ChainedContext并且你希望子模板的#set能反向影响父模板那就需要去掉这层包装直接传递原始 Context 给#parse。需要注意的是这套修改影响面可能很大——去掉子模板隔离后所有子模板的#set都能污染父模板变量冲突风险直接上升。我个人的建议是优先做模板重构其次才是改 Java 包装层因为模板重构可以把影响范围控制在单个模板文件内风险更可控。4.3 一套能落地的 Velocity 模板变量使用规范修复完这次问题后我给自己定了一套模板编写规范这里直接分享出来第一所有“输出型”变量必须在模板最顶部完成赋值。不要依赖子模板里的#set产生新变量再回传所有变量要么来自全局 Context要么在顶层一次性算好。第二少用隐式引用。输出变量一律使用${var}形式不要用$var。区别在于$var后面的内容如果直接跟了英文字母或数字会被吞进变量名里。最典型的教训是$baseUrl/image/$id这种写法如果不加花括号Velocity 会把整个image/image/123当成变量名结果输出一片空白。第三子模板不要依赖父模板里“后面才定义”的变量。渲染顺序是由上到下的单行道子模板被#parse的位置一旦确定它在执行时只能看到它之前定义过的东西。你可以把需要传递的变量统一放到context.put()里在入口处一次性放好而不是在模板中间零散地#set。第四尽量用宏代替深层嵌套的子模板。Velocity 的宏#macro在模板编译阶段就会被解析变量绑定上更可控。而#parse是运行时加载作用域行为更飘。我的经验是如果只是复用一小段 UI 结构用宏如果是完整的文件级模块比如整个页头、整个页脚才用#parse。5. 常见问题速查表与避坑经验我在这个项目里前前后后踩了不少坑整理成几个高频问题和对应的解决策略给遇到类似问题的朋友一个快速索引。现象可能原因排查方向修复建议子模板里变量全部为空用了#include加载子模板检查指令类型改用#parse变量在单模板里能渲染嵌套后为空子模板里通过#set修改的变量无法回传检查变量赋值位置将共享变量在入口统一设置输出出现${userName}原样字符串变量名拼写错误或 Context 未引入检查 key 拼写和 Java 代码修正拼写或补 put输出出现$后面跟变量名原样漏写花括号变量名被子字符串吞掉检查是否用了${}统一用${var}形式修改模板后无变化模板缓存未刷新检查 modificationCheckInterval配置热加载或重启验证子模板内容路径正确但加载不到相对路径解析规则不同检查#parse路径写法改用绝对路径定位资源子模板里#if条件判断总为 false后台返回的是字符串而不是布尔检查 Java 端类型转成布尔或对比字符串这里面有三点我特别想强调。一是“变量空”和“模板没加载”要分开排查。很多人遇到变量为空就一个劲地查变量名、查 Context但实际问题是#parse的路径写错了子模板压根没解析。你加一个调试注释就能快速区分比反复改 Java 代码强一百倍。二是#parse的嵌套层数不要太深。我有一次遇到一个问题三层嵌套的模板里第二层的变量传递全靠#set第三层读到的值总是错乱的。后来把第三层模板合并到第二层问题自然消失了。代码分层有好处模板嵌套分层带来的心智负担在一段时间后一定会超过收益不值得硬扛。三是生产环境的模板渲染不要盲目开热加载。文件系统轮询在低并发下没问题但高并发场景下会引入不必要的 IO 开销。我见过一个线上系统模板修改检查间隔配成了 1 秒高峰期 CPU 飙高排查半天最后定位到是模板引擎在反复 stat 文件。开发环境尽兴生产环境克制。另外Velocity 的版本差异也会导致行为不同。如果你们项目用的是 2.x#parse的局部作用域处理比 1.x 更严格变量遮蔽行为更干净。升级版本有可能破坏现有模板逻辑建议升级前先全量跑一遍渲染测试用例。我还想单独提一个跟模板本身关系不大但经常会和变量问题混淆的场景——字符编码。子模板文件如果保存为 GBK而引擎读的时候按 UTF-8 解析中文是乱码变量名如果是中文 key 也可能出现解析异常。这种问题通常会伴随满屏 “?????”比较容易识别但如果是英文变量名配中文内容乱码只影响内容不影响逻辑容易被忽略。解决办法是统一文件编码和引擎输入编码全部走 UTF-8并且在工程里用编码检查插件卡控避免有人手动改成 GBK 保存。6. 一些真实的调参记录最后分享一段实际调试时的参数配置。我们的 velocity.properties 最终定成这样resource.loader file file.resource.loader.class org.apache.velocity.runtime.resource.loader.FileResourceLoader file.resource.loader.path /opt/app/templates file.resource.loader.cache true file.resource.loader.modificationCheckInterval 60 input.encoding UTF-8 output.encoding UTF-8 directive.parse.max.depth 10 directive.foreach.max.errors 10modificationCheckInterval设成 60 秒既能让发版后最快 1 分钟内自动加载新模板又不会过于频繁地扫描文件系统。directive.parse.max.depth限制嵌套深度为 10 层防止有人写出特别离谱的递归嵌套把线程栈打爆。directive.foreach.max.errors则是限制循环内部的报错次数避免死循环导致日志刷屏。这套配置在正常业务流量下稳定跑了大半年没有再出现过子模板变量渲染缺失的问题。如果你现在正被 Velocity 子模板变量问题折磨我的建议是先把这篇文章里的排查顺序走一遍先确认子模板有没有被正确#parse再确认变量在父模板的执行点是否已经存在然后检查子模板里有没有反向#set污染或依赖父模板未定义的变量最后再看缓存和编码。百分之九十的问题能在这四步里解决。剩下的百分之十大概率就要往项目封装层和第三方依赖版本的方向去查了。