如何在Handlebars模板中正确重命名指定变量

关于内置工具的说明 #

Handlebars 没有提供直接的变量重命名API，但配套提供了完整的AST解析、遍历、打印工具，不需要手动处理字符串替换和位置计算，就能覆盖所有边界场景。

Handlebars AST 定位规则说明 #

行列定位遵循通用AST规范：

• line 从1开始计数，每遇到一个\n换行符行数加1
• column 从0开始计数，代表当前行从行首到节点位置的字符偏移，制表符按单个字符计算，不做展开
• loc.start 标记节点第一个字符的位置，loc.end 标记节点最后一个字符的下一个位置，和ESTree规范一致。例如{{FOO}}中的FOO，start.column值为2，end.column值为5，对应字符串索引2、3、4三个位置为F/O/O三个字符

原有实现的问题 #

你写的实现无法正常运行主要有三个原因：

• 每次替换字符串后，后续所有节点的位置都会发生偏移，没有同步更新偏移量，会导致后续替换位置完全错乱
• 仅遍历了顶层块语句和它的直接子节点，没有处理嵌套块、helper子表达式、部分传参等场景，漏了大量边界情况
• 直接对切片做字符串替换，遇到FOO.FOO这类根变量名和属性名重名的场景时，很容易误替换属性部分的内容

可直接使用的正确实现 #

利用Handlebars自带的AST能力，不需要手动计算位置，直接修改AST节点后重新打印模板即可：

import Handlebars from "handlebars";
import type { Node, PathExpression, Program } from "handlebars";

// 深度遍历AST所有节点
function traverseNode(node: Node | null | undefined, callback: (node: Node) => void) {
  if (!node || typeof node !== "object") return;
  callback(node);
  for (const key of Object.keys(node)) {
    const val = (node as Record<string, unknown>)[key];
    if (Array.isArray(val)) {
      val.forEach(item => traverseNode(item as Node, callback));
    } else if (typeof val === "object" && val !== null) {
      traverseNode(val as Node, callback);
    }
  }
}

export const renameHandlebarsVariables = (
  oldName: string,
  newName: string,
  template: string
): string => {
  // 解析得到原始AST，不做任何预处理
  const ast = Handlebars.parseWithoutProcessing(template) as Program;
  // 遍历所有节点，仅修改匹配的根级路径变量
  traverseNode(ast, (node) => {
    if (node.type === "PathExpression") {
      const path = node as PathExpression;
      // 排除@开头的内置数据变量，仅替换根变量名
      if (!path.data && path.parts[0] === oldName) {
        path.parts[0] = newName;
        // 转义正则特殊字符，避免匹配异常
        const escapeReg = /[.*+?^${}()|[\]\\]/g;
        path.original = path.original.replace(
          new RegExp(`^${oldName.replace(escapeReg, "\\$&")}(?=\\.|$)`),
          newName
        );
      }
    }
  });
  // 将修改后的AST序列化回模板字符串
  return Handlebars.print(ast);
}

这个实现自动覆盖所有边界场景：

• 不会误改普通文本内容中与变量名重名的字符串
• 不会误改路径属性段中与根变量重名的部分，比如FOO.FOO替换后会正确得到DOG.FOO
• 支持任意嵌套的块语句、helper参数、子表达式、部分传参等所有Handlebars语法场景
• 不需要手动计算任何位置偏移，不会出现替换后格式错乱的问题

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