最完整mustache.js入门指南：从安装到高级用法全解析

你还在为前端模板渲染烦恼吗？还在纠结如何优雅地将数据与视图分离？本文将带你全面掌握mustache.js——这款轻量级、无逻辑的JavaScript模板引擎，从基础安装到高级用法，让你10分钟内上手，轻松解决90%的模板渲染场景。

读完本文你将获得：

• 3种快速安装mustache.js的方法
• 5类核心模板标签的使用技巧
• 7个实战案例（含代码模板）
• 性能优化与常见问题解决方案

什么是mustache.js？

mustache.js是一款实现了Mustache模板系统的JavaScript库，遵循"无逻辑"设计理念，通过{{}}标记将数据与模板分离。它可以运行在浏览器和Node.js环境中，支持多种模块系统（CommonJS、AMD、ESM），广泛应用于Web开发、静态站点生成等场景。

项目核心文件：mustache.js

快速安装

npm安装（推荐）

npm install mustache --save

国内CDN引入

<script src="https://cdn.bootcdn.net/ajax/libs/mustache.js/4.2.0/mustache.min.js"></script>

源码引入

从仓库获取源码：

git clone https://gitcode.com/gh_mirrors/mu/mustache.js

引入本地文件：

<script src="mustache.js"></script>

基础用法

核心渲染函数

mustache.js的核心是Mustache.render()方法，基本语法：

const result = Mustache.render(template, view, partials);

第一个示例

模板：

<h1>Hello {{name}}!</h1>
<p>你今年{{age}}岁，来自{{address.city}}</p>

数据：

const view = {
  name: "小明",
  age: 25,
  address: {
    city: "北京"
  }
};

渲染结果：

<h1>Hello 小明!</h1>
<p>你今年25岁，来自北京</p>

完整代码示例可参考test/_files/simple.js和test/_files/simple.mustache

模板标签全解析

1. 变量标签

• 转义输出：{{variable}}（默认HTML转义）
• 原始输出：{{{variable}}} 或 {{&variable}}

示例：

<!-- 模板 -->
<div>转义输出: {{html}}</div>
<div>原始输出: {{{html}}}</div>

<!-- 数据 -->
{
  "html": "<b>加粗文本</b>"
}

<!-- 结果 -->
<div>转义输出: &lt;b&gt;加粗文本&lt;/b&gt;</div>
<div>原始输出: <b>加粗文本</b></div>

2. 条件判断

使用{{#key}}和{{/key}}包裹条件区块，当key为真值时渲染。

真值情况：非null、非undefined、非false、非空数组 假值情况：null、undefined、false、空数组

{{#isLogin}}
  <span>欢迎回来，{{username}}!</span>
{{/isLogin}}
{{^isLogin}}
  <button>登录</button>
{{/isLogin}}

3. 循环迭代

对数组数据自动迭代，使用{{.}}访问当前元素：

<!-- 模板 -->
<ul>
  {{#hobbies}}
    <li>{{.}}</li>
  {{/hobbies}}
</ul>

<!-- 数据 -->
{
  "hobbies": ["读书", "运动", "编程"]
}

<!-- 结果 -->
<ul>
  <li>读书</li>
  <li>运动</li>
  <li>编程</li>
</ul>

复杂对象迭代示例：test/_files/complex.js

4. 部分模板(Partials)

复用模板片段，使用{{>partialName}}引入：

主模板：

<div class="user">
  {{>userHeader}}
  <p>{{bio}}</p>
</div>

部分模板(userHeader)：

<h2>{{name}}</h2>
<div class="avatar" style="background-image: url({{avatar}})"></div>

渲染代码：

Mustache.render(template, view, {
  userHeader: userHeaderTemplate
});

完整示例：test/_files/partial_template.js

5. 自定义分隔符

通过{{=新分隔符=}}临时更改标签分隔符，解决与其他模板冲突：

{{=<% %>=}}
<!-- 现在使用 <% %> 作为标签分隔符 -->
<div><%name%></div>
<%={{ }}=%>
<!-- 恢复默认分隔符 -->
{{name}}

高级用法

嵌套上下文

使用点符号访问深层对象属性：

<!-- 模板 -->
{{#user}}
  <h1>{{name.first}} {{name.last}}</h1>
  <p>邮箱: {{contact.email}}</p>
{{/user}}

<!-- 数据 -->
{
  "user": {
    "name": {
      "first": "张",
      "last": "三"
    },
    "contact": {
      "email": "[e-mail]"
    }
  }
}

示例文件：test/_files/dot_notation.js

函数作为数据

在视图对象中定义函数，模板中直接调用：

const view = {
  price: 99,
  quantity: 3,
  total: function() {
    return this.price * this.quantity;
  },
  formattedTotal: function() {
    return "¥" + (this.price * this.quantity).toFixed(2);
  }
};

<!-- 模板 -->
<div>单价: {{price}}</div>
<div>数量: {{quantity}}</div>
<div>合计: {{formattedTotal}}</div>

<!-- 结果 -->
<div>单价: 99</div>
<div>数量: 3</div>
<div>合计: ¥297.00</div>

预编译模板

对于频繁使用的模板，可提前编译提升性能：

// 预编译
const template = "Hello {{name}}!";
Mustache.parse(template); // 编译并缓存

// 多次渲染
for(let i = 0; i < 100; i++) {
  Mustache.render(template, {name: "用户" + i});
}

命令行工具

mustache.js提供命令行工具，方便批量处理模板：

安装命令行工具

npm install -g mustache

基本用法

mustache 数据文件.json 模板文件.mustache > 输出文件.html

示例

# 数据文件(data.json)
{
  "title": "命令行示例",
  "items": ["选项1", "选项2", "选项3"]
}

# 执行命令
mustache data.json template.mustache > output.html

更多CLI测试用例：test/cli-test.js

性能优化指南

1. 模板缓存：利用内部缓存机制，避免重复解析相同模板
2. 预编译：对静态模板提前执行Mustache.parse()
3. 减少嵌套：复杂嵌套会增加渲染时间，适当拆分模板
4. 数据处理：渲染前预处理数据，避免在模板中进行复杂计算

常见问题解决方案

1. 空白字符处理

mustache.js会保留模板中的空白字符，可通过以下方式控制：

• 使用注释标记{{! 这里的内容会被忽略 }}
• 合理设置模板格式，避免不必要的空白

2. 条件判断空数组

空数组会被视为假值，可结合反向部分标签处理：

{{#items}}
  <li>{{.}}</li>
{{/items}}
{{^items}}
  <li>没有数据</li>
{{/items}}

3. 避免原型污染

mustache.js默认会查找对象原型链，可通过自定义Mustache.escape方法限制：

Mustache.escape = function(text) {
  // 自定义处理逻辑
  return text;
};

总结

mustache.js以其简洁的API、无逻辑设计和广泛的兼容性，成为前端模板引擎的优秀选择。通过本文介绍的安装方法、核心标签、高级技巧和最佳实践，你已经具备解决大多数模板渲染场景的能力。

官方文档：README.md
测试用例集合：test/
版本更新记录：CHANGELOG.md

掌握mustache.js，让你的数据渲染代码更优雅、更可维护。现在就尝试将它应用到你的项目中吧！