定制过Zendesk Guide主题的开发者，几乎都撞过同一个坑：在主题模板的script标签里写了一段普通的JavaScript代码，保存并预览后，页面上的脚本突然报错，或者页面上直接显示出一些本不该出现的花括号字符。排查半天才发现，罪魁祸首是Guide底层使用的Handlebars模板引擎。它会把模板文件中所有的{{}}当成自己的插值占位符去解析，哪怕这些花括号出现在JavaScript代码里。本文就来系统讲清楚这个冲突的产生机制，以及几种经过验证的解决方案。
冲突是怎么产生的：理解Handlebars的解析机制
Zendesk Guide的主题模板文件，本质上是一组Handlebars模板。当用户访问帮助中心页面时，Zendesk服务端会先读取这些模板文件，把其中的{{placeholder}}替换成实际内容，再把渲染结果返回给浏览器。问题在于，这个替换发生在服务端，而且是全文扫描——它不区分花括号出现在HTML结构里，还是出现在script标签内的JavaScript代码里。
举个例子，如果你在模板里写了下面这样的jQuery代码：
$(document).ready(function() {
var settings = {};
if (typeof settings === 'object' && settings !== null) {
// 这里出现了{{}}结构的可能性
}
});
上面这段代码本身没有语法问题，但一旦你在代码里写了对象字面量嵌套，比如var data = {{id: 1}}这种形式（虽然写法不规范，但确实有人这么写），Handlebars会尝试把{{id: 1}}当成一个helper调用，解析失败后要么报错，要么输出一段空的、错乱的字符串，最终浏览器拿到的JavaScript就是一段残缺代码。
更常见的场景是三花括号。Handlebars中{{{content}}}表示不转义输出，有些开发者在写代码注释或字符串时无意间凑出了连续三个花括号，直接触发了引擎的不转义输出逻辑，导致模板渲染阶段就抛出异常，整个页面白屏。
方案一：用Handlebars原生转义语法隔离
Handlebars本身提供了转义机制：使用\{{可以让引擎跳过这个占位符，原样输出。也就是说，当你的JavaScript代码里确实需要出现{{}}字面量时，可以在前面加上反斜杠转义：
// 模板中写法
var config = \{{ "name": "helper" }};
// 渲染后浏览器实际收到
var config = {{ "name": "helper" }};
这个方案的好处是改动最小，不需要调整文件结构。但它也有明显的缺陷：反斜杠只对紧随其后的那一个花括号生效，如果代码中{{}}出现频率很高，逐个添加转义符既繁琐又容易遗漏。而且一旦后来维护时不理解这些反斜杠的来历，随手删掉就会重新引入bug。所以这种方式只适合偶尔出现一两处花括号的场景。
另外要注意，转义只针对开头的\{{即可，结束的}}不需要转义。这一点和很多其他模板引擎不同，写多了反而会在输出中留下多余的反斜杠。
方案二：把JavaScript抽离到assets目录下的外部文件
这是官方文档推荐、也是实践中最稳妥的做法。Zendesk Guide主题允许在assets文件夹中放置自定义的script.js文件，并在页面模板中通过script标签引入：
<script src="{{asset 'script.js'}}"></script>
关键在于：Handlebars只解析模板文件本身，不会去解析assets目录下的js文件内容。也就是说，script.js文件里的代码完全不会经过模板引擎处理，你可以放心地写任何包含花括号的JavaScript，jQuery的$.each、正则表达式、对象嵌套统统没有问题。
这样做还有一个附带的好处：脚本文件会被浏览器独立缓存，用户重复访问帮助中心时不需要重新下载，加载速度更快。同时代码逻辑和模板结构分离，后期维护时定位问题也清晰得多——模板管结构，script.js管行为，各司其职。
唯一的限制是外部脚本无法直接读取模板中的动态数据。如果脚本需要用到页面里的动态值，正确做法是让Handlebars先把数据渲染到一个全局变量或data-属性上，外部脚本再从DOM里读取：
<div id="page-data" data-locale="{{locale}}" data-current-user="{{current_user.name}}"></div>
<script src="{{asset 'script.js'}}"></script>
// script.js 中
$(function() {
var $data = $('#page-data');
var locale = $data.data('locale');
var userName = $data.data('currentUser');
console.log('当前语言:', locale, '用户:', userName);
});
方案三：Handlebars预编译与模板隔离
如果你的需求更复杂，比如需要在客户端动态拼接HTML片段，直接在Guide模板里写Handlebars客户端模板必然冲突。这时可以采用预编译思路：把客户端模板字符串放在JavaScript的字符串常量中构建，而不是直接写在模板文件里。
具体做法是借助数组和字符串拼接，把花括号拆开，让Handlebars在服务端解析时看不到连续的{{：
// script.js 中动态构建模板
var brace = '{';
var tpl = brace + '{#each items}}'
+ '<li>' + brace + '{this.name}}</li>'
+ brace + '{{/each}}';
// 编译为客户端模板函数
var template = Handlebars.compile(tpl);
$('#list').html(template({ items: [{name: '文章一'}, {name: '文章二'}] }));
由于script.js不会被服务端的Handlebars触碰，这种拼接方式完全安全。在浏览器端再调用Handlebars.compile编译模板字符串，就实现了所谓编译隔离：服务端渲染归服务端，客户端动态渲染归客户端，两边互不干扰。
需要注意的是，如果你打算在客户端使用Handlebars，要自行引入它的运行时库，Zendesk Guide页面默认并不暴露可用的Handlebars全局对象。可以从官方CDN引入handlebars.runtime的压缩版本，体积很小，不影响页面性能。编译好的模板函数建议缓存起来，避免每次事件触发都重新compile，造成不必要的性能开销。
几种方案的对比与选择建议
把三种方案放在一起比较一下。反斜杠转义适合应急或花括号极少的场景，改动量最小但可维护性差；外部脚本抽离是绝大多数情况下的首选，结构清晰、缓存友好，配合data属性传递动态数据几乎能覆盖所有定制需求；客户端预编译则适合需要高度动态渲染列表、筛选结果的场景，是前者的进阶补充。
实际项目中，推荐把方案二作为基础架构固定下来：所有自定义jQuery代码统一放assets目录，模板里只留数据出口。遇到确实需要客户端模板的时候，再叠加方案三。方案一可以彻底放弃，除非是修改历史遗留代码来不及重构时的临时手段。
最后提醒一点，排查这类问题时不要只盯着浏览器控制台，因为脚本到达浏览器时已经被破坏了，报错位置往往不准确。正确的调试方式是在Zendesk主题编辑器里打开预览，查看页面源代码，确认服务端渲染后的实际输出长什么样，再判断是哪个环节出了问题。养成先看渲染结果再调试脚本的顺序，能省下大量无谓的排查时间。
Zendesk GuideHandlebarsjQuery冲突修改时间：2026-09-08 21:03:19