如何避免Webpack生成含$的变量名，兼容Apache Velocity引擎

方案一：修改构建配置，避免生成$开头的变量名 #

Webpack生产模式下默认用TerserPlugin做代码混淆压缩，部分场景会生成$i这类$开头的变量名。我们可以通过配置Terser，强制变量名避开$：

修改webpack.config.cjs #

添加optimization配置，自定义Terser的混淆规则：

const HtmlBundlerPlugin = require("html-bundler-webpack-plugin");
const TerserPlugin = require('terser-webpack-plugin'); // Webpack 5+可省略此引入

module.exports = {
  // ... 原有module、resolve、plugins配置
  optimization: {
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          mangle: {
            toplevel: true, // 混淆顶层变量
            safari10: true, // 兼容Safari 10
            keep_classnames: false,
            keep_fnames: false,
            // 核心：禁用$开头的变量命名，Terser会自动用纯字母/下划线开头的名称
          },
          format: {
            comments: false, // 移除注释
            ascii_only: true, // 确保变量名仅含ASCII字符，避免特殊符号
          },
        },
      }),
    ],
  },
};

这个配置从根源上避免生成带$的变量，彻底解决Velocity解析冲突。

方案二：构建后批量替换$开头的变量名 #

如果方案一无法覆盖所有场景（比如第三方依赖生成的$变量），可以在构建完成后用脚本批量替换：

方法1：简单正则替换（快速临时方案） #

1. 在package.json中添加构建后脚本：

"scripts": {
  "build": "webpack --mode production",
  "postbuild": "node scripts/replace-dollar-vars.js"
}

2. 创建scripts/replace-dollar-vars.js：

const fs = require('fs');
const path = require('path');

// 替换目标HTML文件路径，根据你的输出目录调整
const htmlPath = path.resolve(__dirname, '../dist/index.html');
let htmlContent = fs.readFileSync(htmlPath, 'utf8');

// 替换独立的$开头变量（跳过字符串中的$，避免误替换）
htmlContent = htmlContent.replace(/(?<!["'])\\?\$([a-zA-Z0-9_]+)\b/g, 'S$1');

fs.writeFileSync(htmlPath, htmlContent, 'utf8');
console.log('$变量名替换完成');

适合临时快速解决，但存在少量边界情况。

方法2：AST解析替换（精准方案） #

通过Babel AST解析JS代码，精准替换变量名，完全避免误替换：

1. 安装依赖：

npm install @babel/parser @babel/traverse @babel/generator @babel/types --save-dev

2. 创建scripts/replace-dollar-vars-ast.js：

const fs = require('fs');
const path = require('path');
const parser = require('@babel/parser');
const traverse = require('@babel/traverse').default;
const generator = require('@babel/generator').default;
const t = require('@babel/types');

const htmlPath = path.resolve(__dirname, '../dist/index.html');
let htmlContent = fs.readFileSync(htmlPath, 'utf8');

// 提取并处理内联脚本
htmlContent = htmlContent.replace(/<script>([\s\S]*?)<\/script>/g, (match, jsCode) => {
  // 解析JS为AST
  const ast = parser.parse(jsCode, {
    sourceType: 'module',
    plugins: ['jsx', 'typescript'],
  });

  // 遍历AST，替换$开头的变量名
  traverse(ast, {
    Identifier(path) {
      const name = path.node.name;
      if (name.startsWith('$')) {
        path.node.name = 'S' + name.slice(1); // 将$i替换为Si
      }
    },
  });

  // 生成修改后的JS代码
  const { code } = generator(ast, { compact: true });
  return `<script>${code}</script>`;
});

fs.writeFileSync(htmlPath, htmlContent, 'utf8');
console.log('AST方式$变量名替换完成');

3. 修改package.json的postbuild脚本指向这个文件即可。

备选方案：Velocity转义处理 #

如果不想修改JS变量名，也可以在Velocity处理前对JS中的$进行转义，让Velocity忽略这些变量：
在构建后的脚本中，将JS里的$i替换为\$i，这样Velocity处理时会保留原始的$：

htmlContent = htmlContent.replace(/\b\$([a-zA-Z0-9_]+)\b/g, '\\$$1');

客户端执行JS时，\$会被解析为正常的$，不影响代码运行。

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