# 【RuoYi-Eggjs】：基于 Handlebars 模板引擎实现服务端渲染

## 前言

在 Web 开发中，选择合适的模板引擎能让前端开发事半功倍。Handlebars 作为一款轻量级的语义化模板引擎，以其简洁的语法和强大的功能深受开发者喜爱。`[ruoyi-eggjs-handlebars](https://github.com/undsky/ruoyi-eggjs-handlebars)` 就是为 Egg.js 框架量身定制的 Handlebars 插件，让你在 Egg.js 中也能享受 Handlebars 的便利。

## 为什么选择 Handlebars？

### 📝 语法简洁直观

Handlebars 使用双花括号 `{{}}` 作为标记，语法清晰易懂：

```html
<h1>Hello {{name}}!</h1>
<p>年龄：{{age}} 岁</p>
```

### 🔒 逻辑分离

Handlebars 强调"无逻辑"模板（logic-less），将业务逻辑与视图层严格分离，模板只负责展示数据，逻辑处理在 Controller 或 Service 层完成。这种设计让代码结构更清晰、更易维护。

### 🎯 功能强大

虽然是"无逻辑"模板，但 Handlebars 通过 Helper 机制提供了丰富的功能扩展，既保持了模板的简洁性，又满足了实际开发的需求。

## 核心特性

### 🚀 性能优化

插件针对不同环境做了优化：

- **开发环境**：每次渲染时重新加载模板，支持热更新
- **生产环境**：启动时预编译所有模板，缓存在内存中，提升渲染性能

### 🧩 Partials 支持

Partials（代码片段）功能让你可以复用页面的公共部分，比如头部、尾部、侧边栏等：

```html

<header>
  <h1>{{title}}</h1>
  <nav>...</nav>
</header>


{{> header}}
```

### 🛠️ 内置实用 Helper

插件内置了几个常用的 Helper，开箱即用：

**1. xif - 强化的条件判断**

支持复杂表达式，比原生的 `{{#if}}` 更强大：

```html
{{#xif "age > 18"}}
  <p>成年人</p>
{{else}}
  <p>未成年</p>
{{/xif}}

{{#xif "score >= 60 && score < 80"}}
  <p>及格</p>
{{/xif}}
```

**2. math - 数学运算**

在模板中直接进行数学计算：

```html
<p>原价：{{price}}</p>
<p>折后价：{{math price "*" 0.8}}</p>
<p>库存剩余：{{math total "-" sold}}</p>
```

**3. link - CSS 引入**

快速引入样式文件，自动处理时间戳：

```html
{{link "/static/css/style.css"}}

```

**4. script - JS 引入**

快速引入脚本文件，同样支持时间戳：

```html
{{script "/static/js/app.js"}}

```

> **时间戳功能**：默认开启，可有效避免浏览器缓存导致的静态资源更新问题。

## 快速上手

### 安装

```bash
npm i ruoyi-eggjs-handlebars --save
```

### 配置

**1. 启用插件**

```js
// config/plugin.js
exports.handlebars = {
  enable: true,
  package: "ruoyi-eggjs-handlebars",
};
```

**2. 基础配置**

```js
// config/config.default.js
config.handlebars = {
  options: {
    data: true,
    compat: true,
    noEscape: false,        // 是否转义 HTML
    strict: false,          // 严格模式
    preventIndent: true,    // 防止自动缩进
  },
  runtimeOptions: {
    allowProtoMethodsByDefault: true,
    allowProtoPropertiesByDefault: true,
  },
  partialsPath: null,       // Partials 目录，默认为 view.root/partials
  ts: true,                 // 静态资源是否添加时间戳
};
```

### 使用示例

**Controller 层**

```js
// app/controller/home.js
class HomeController extends Controller {
  async index() {
    const { ctx } = this;
    await ctx.render('index.html', {
      title: '欢迎使用 Handlebars',
      user: {
        name: '张三',
        age: 25,
      },
      products: [
        { name: '商品A', price: 99 },
        { name: '商品B', price: 199 },
      ],
    });
  }
}
```

**模板文件**

```html

<!DOCTYPE html>
<html>
<head>
  <title>{{title}}</title>
  {{link "/static/css/style.css"}}
</head>
<body>
  {{> header}}
  
  <main>
    <h2>用户信息</h2>
    <p>姓名：{{user.name}}</p>
    <p>年龄：{{user.age}}</p>
    
    {{#xif "user.age >= 18"}}
      <p class="badge">成年用户</p>
    {{/xif}}
    
    <h2>商品列表</h2>
    <ul>
      {{#each products}}
        <li>
          {{this.name}} - 
          <span class="price">¥{{this.price}}</span>
          <span class="discount">折后价：¥{{math this.price "*" 0.8}}</span>
        </li>
      {{/each}}
    </ul>
  </main>
  
  {{> footer}}
  {{script "/static/js/app.js"}}
</body>
</html>
```

## 实战场景

### 场景 1：后台管理系统布局

后台系统通常有固定的布局结构，使用 Partials 可以很好地复用：

```
app/view/
├── partials/
│   ├── header.html      # 顶部导航
│   ├── sidebar.html     # 侧边栏
│   └── footer.html      # 底部
├── layout.html          # 布局模板
├── user/
│   ├── list.html        # 用户列表
│   └── detail.html      # 用户详情
└── dashboard.html       # 仪表盘
```

**布局模板**

```html

<!DOCTYPE html>
<html>
<head>
  <title>{{title}} - 管理后台</title>
  {{link "/static/css/admin.css"}}
</head>
<body>
  {{> header}}
  
  <div class="container">
    {{> sidebar}}
    
    <main class="content">
      {{{body}}}  
    </main>
  </div>
  
  {{> footer}}
  {{script "/static/js/admin.js"}}
</body>
</html>
```

### 场景 2：数据列表渲染

使用 Handlebars 的 `{{#each}}` 和内置 Helper 轻松实现数据列表：

```html

<div class="user-list">
  <h2>用户列表（共 {{users.length}} 人）</h2>
  
  <table>
    <thead>
      <tr>
        <th>序号</th>
        <th>姓名</th>
        <th>年龄</th>
        <th>状态</th>
        <th>操作</th>
      </tr>
    </thead>
    <tbody>
      {{#each users}}
        <tr>
          <td>{{math @index "+" 1}}</td>
          <td>{{this.name}}</td>
          <td>{{this.age}}</td>
          <td>
            {{#xif "this.age >= 18"}}
              <span class="badge success">成年</span>
            {{else}}
              <span class="badge warning">未成年</span>
            {{/xif}}
          </td>
          <td>
            <a href="/user/{{this.id}}">查看</a>
            <a href="/user/{{this.id}}/edit">编辑</a>
          </td>
        </tr>
      {{/each}}
    </tbody>
  </table>
</div>
```

### 场景 3：条件渲染

使用 `xif` Helper 实现复杂的条件判断：

```html

<div class="product-detail">
  <h1>{{product.name}}</h1>
  <p class="price">¥{{product.price}}</p>
  
  
  {{#xif "product.stock > 10"}}
    <span class="stock success">库存充足</span>
  {{else}}
    {{#xif "product.stock > 0"}}
      <span class="stock warning">仅剩 {{product.stock}} 件</span>
    {{else}}
      <span class="stock danger">已售罄</span>
    {{/xif}}
  {{/xif}}
  
  
  {{#xif "product.discount < 1"}}
    <div class="discount-info">
      <p>原价：¥{{product.price}}</p>
      <p>折扣价：¥{{math product.price "*" product.discount}}</p>
      <p>节省：¥{{math product.price "-" (math product.price "*" product.discount)}}</p>
    </div>
  {{/xif}}
</div>
```

## 最佳实践

### 1. 合理组织 Partials

将公共部分抽取为 Partials，提高代码复用性：

```
partials/
├── common/
│   ├── header.html      # 页头
│   ├── footer.html      # 页脚
│   └── meta.html        # Meta 标签
├── components/
│   ├── pagination.html  # 分页组件
│   ├── breadcrumb.html  # 面包屑
│   └── alert.html       # 提示框
└── forms/
    ├── input.html       # 输入框
    └── select.html      # 下拉框
```

### 2. 善用内置 Helper

充分利用 `xif` 和 `math` 简化模板逻辑：

```html

{{#xif "score >= 90"}}
  <span class="grade">优秀</span>
{{else}}
  {{#xif "score >= 60"}}
    <span class="grade">及格</span>
  {{else}}
    <span class="grade">不及格</span>
  {{/xif}}
{{/xif}}



```

### 3. 静态资源管理

合理使用时间戳功能，避免缓存问题：

```js
// config/config.default.js
config.handlebars = {
  ts: process.env.NODE_ENV === 'production',  // 生产环境启用
};
```

### 4. 避免过度嵌套

虽然 Handlebars 支持嵌套，但过度嵌套会降低可读性：

```html

{{#each users}}
  {{> userCard}}
{{/each}}


{{#each categories}}
  {{#each this.products}}
    {{#each this.variants}}
      ...
    {{/each}}
  {{/each}}
{{/each}}
```

## 配置参数详解

### 编译选项（options）

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| data | Boolean | true | 是否启用 @data 跟踪 |
| compat | Boolean | true | 允许递归查找 |
| noEscape | Boolean | false | 是否禁用 HTML 转义 |
| strict | Boolean | false | 严格模式（缺失参数时抛异常） |
| preventIndent | Boolean | true | 防止自动缩进 |
| ignoreStandalone | Boolean | true | 不移除单独的标签 |

### 运行时选项（runtimeOptions）

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| allowProtoMethodsByDefault | Boolean | true | 允许访问原型方法 |
| allowProtoPropertiesByDefault | Boolean | true | 允许访问原型属性 |

### 插件选项

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| partialsPath | String/Array | null | Partials 目录路径 |
| ts | Boolean | true | 静态资源是否添加时间戳 |

## 总结

`ruoyi-eggjs-handlebars` 是一个功能完善、性能优异的 Egg.js 模板引擎插件，它的优势在于：

- **简单易用**：语法简洁，学习成本低
- **性能优秀**：生产环境预编译，开发环境热更新
- **功能实用**：内置 Helper 满足常见需求
- **代码复用**：Partials 机制支持组件化开发
- **灵活配置**：丰富的配置项，适应不同场景

如果你正在使用 Egg.js 开发传统的服务端渲染应用，或者需要一个轻量级的模板引擎来生成 HTML 邮件、导出报表等，`ruoyi-eggjs-handlebars` 都是一个不错的选择！

-----

+ 插件地址：[ruoyi-eggjs-handlebars](https://github.com/undsky/ruoyi-eggjs-handlebars)
+ 项目地址：[RuoYi-Eggjs](https://github.com/undsky/ruoyi-eggjs)
+ 开发文档：[RuoYi-Eggjs 文档](https://www.undsky.com/blog/?category=RuoYi-Eggjs#)

在 Web 开发中，选择合适的模板引擎能让前端开发事半功倍。Handlebars 作为一款轻量级的语义化模板引擎，以其简洁的语法和强大的功能深受开发者喜爱。[ruoyi-eggjs-handlebars](https://github.com/undsky/ruoyi-eggjs-handlebars) 就是为 Egg.js 框架量身定制的 Handlebars 插件，让你在 Egg.js 中也能享受 Handlebars 的便利。

【RuoYi-Eggjs】：基于 Handlebars 模板引擎实现服务端渲染

在 Web 开发中，选择合适的模板引擎能让前端开发事半功倍。Handlebars 作为一款轻量级的语义化模板引擎，以其简洁的语法和强大的功能深受开发者喜爱。[ruoyi-eggjs-handlebars](https://github.com/undsky/ruoyi-eggjs-handlebars) 就是为 Egg.js 框架量身定制的 Handlebars 插件，让你在 Egg.js 中也能

前端

开发工具

RuoYi-Eggjs-Handlebars是为Egg.js框架定制的Handlebars插件，支持服务端渲染。提供简洁语法、逻辑分离、性能优化和内置Helper等功能，包含xif条件判断、math数学运算等实用工具。支持Partials代码复用，开发环境热更新，生产环境预编译缓存，是构建高效Web应用的理想选择。

2026新春采购季

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【RuoYi-Eggjs】：基于 Handlebars 模板引擎实现服务端渲染-腾讯云开发者社区-腾讯云

【RuoYi-Eggjs】：基于 Handlebars 模板引擎实现服务端渲染

【RuoYi-Eggjs】：基于 Handlebars 模板引擎实现服务端渲染

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐