express-handlebars与webpack多页面应用：无法导出局部模板和助手函数

我之前在做类似的服务端+客户端混合Handlebars渲染项目时，也碰到过一模一样的问题——服务端用express-handlebars顺风顺水，但到了客户端想用Webpack打包模板时，partials和helpers死活没法共享。折腾了好一阵，总结出几个亲测有效的方案，分享给你：

核心思路：分离共享资源，两端分别注册 #

本质问题是express-handlebars的服务端模板环境和客户端Handlebars环境是独立的，所以我们需要把partials和helpers抽成两端都能引用的独立文件，再分别在服务端和客户端注册到各自的Handlebars实例中。

1. 重构目录结构，隔离共享资源 #

先把共享的partials和helpers从服务端目录里抽出来，比如这样：

project/
├── src/
│   ├── server/
│   │   ├── app.js          # Express入口
│   │   └── views/          # 服务端页面模板（用布局）
│   └── shared/
│       ├── handlebars/
│       │   ├── partials/   # 共享的页眉、页脚等partials
│       │   │   ├── header.hbs
│       │   │   └── footer.hbs
│       │   └── helpers/    # 共享的格式化函数等helpers
│       │       ├── formatDate.js
│       │       └── truncateText.js
│   └── client/
│       ├── js/
│       │   ├── entry/      # 多页面入口文件
│       │   │   ├── page1.js
│       │   │   └── page2.js
│       │   └── handlebars-init.js # 客户端Handlebars初始化文件
│       └── templates/      # 客户端专属模板（如果有的话）
└── webpack.config.js

2. 服务端配置：让express-handlebars加载共享资源 #

在你的Express配置文件里，指定partials和helpers的路径为共享目录：

// src/server/app.js
const express = require('express');
const exphbs = require('express-handlebars');
const path = require('path');

const app = express();

// 配置express-handlebars
const hbs = exphbs.create({
  defaultLayout: 'main', // 服务端主布局
  layoutsDir: path.join(__dirname, 'views/layouts'),
  partialsDir: path.join(__dirname, '../shared/handlebars/partials'), // 指向共享partials
  helpers: require('../shared/handlebars/helpers/index.js') // 导入共享helpers（可以写个index统一导出）
});

app.engine('handlebars', hbs.engine);
app.set('view engine', 'handlebars');

3. 客户端配置：用Webpack打包并注册资源 #

首先安装必要的依赖：

npm install handlebars handlebars-loader --save-dev

然后配置Webpack，让它能处理.hbs文件：

// webpack.config.js
module.exports = {
  // 多页面入口配置，根据你的项目调整
  entry: {
    page1: './src/client/js/entry/page1.js',
    page2: './src/client/js/entry/page2.js'
  },
  module: {
    rules: [
      {
        test: /\.hbs$/,
        use: 'handlebars-loader',
        exclude: /node_modules/
      }
    ]
  },
  optimization: {
    splitChunks: {
      chunks: 'all',
      // 把共享的Handlebars代码抽成公共chunk，减少重复打包
      cacheGroups: {
        handlebars: {
          test: /[\\/]node_modules[\\/]handlebars[\\/]/,
          name: 'handlebars-vendor',
          chunks: 'all'
        }
      }
    }
  }
};

接下来写客户端的Handlebars初始化文件，统一注册partials和helpers：

// src/client/js/handlebars-init.js
import Handlebars from 'handlebars';

// 注册共享partials
import headerPartial from '../../shared/handlebars/partials/header.hbs';
Handlebars.registerPartial('header', headerPartial);

import footerPartial from '../../shared/handlebars/partials/footer.hbs';
Handlebars.registerPartial('footer', footerPartial);

// 注册共享helpers
import { formatDate, truncateText } from '../../shared/handlebars/helpers/index.js';
Handlebars.registerHelper('formatDate', formatDate);
Handlebars.registerHelper('truncateText', truncateText);

// 导出初始化后的Handlebars实例
export default Handlebars;

最后在每个页面的入口文件里导入这个初始化好的Handlebars，就可以直接用partials和helpers了：

// src/client/js/entry/page1.js
import Handlebars from '../handlebars-init.js';
import pageTemplate from '../../templates/page1.hbs';

// 用Ajax获取数据后渲染
fetch('/api/page1-data')
  .then(res => res.json())
  .then(data => {
    const html = pageTemplate(data);
    document.getElementById('content').innerHTML = html;
  });

4. 踩过的坑提醒 #

• 确保服务端用的express-handlebars依赖的Handlebars版本，和客户端安装的handlebars版本一致，避免语法兼容性问题。
• 如果helpers里有服务端专属的API（比如Node.js的path模块），要把这部分逻辑拆分出来，只把客户端能用的helpers放到共享目录。
• 多页面应用里，如果每个页面需要的partials/helpers不一样，可以在初始化文件里做条件注册，或者给每个页面单独写初始化逻辑。

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