Handlebars compile()返回undefined，结合Puppeteer生成PDF失败如何解决？

AI 小北

2026-9-25

问题排查与解决方案

高频出错点1：`fs`模块导入错误

你当前使用await fs.readFile，如果导入的是原生fs模块而非Promise版本，readFile默认走回调逻辑，await拿到的返回值为undefined，后续编译自然没有内容。修正导入方式：

const fs = require('fs').promises; // 启用Promise版本的fs API

如果是ESM规范的项目，还要额外处理__dirname不存在的问题：

import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

高频出错点2：模板文件存在性判断逻辑错误

path.join无论路径是否真实存在都会返回字符串，你写的if (!filePath)判断永远不会触发，无法捕获路径拼写错误、模板文件缺失的问题。修正逻辑：

async function renderTemplate(data, templateName) {
  const filePath = path.join(__dirname, "templates", `${templateName}.hbs`);
  // 新增文件存在性校验
  try {
    await fs.access(filePath);
  } catch (e) {
    throw new Error(`模板文件不存在：${filePath}`);
  }
  const html = await fs.readFile(filePath, "utf-8");
  // 新增日志确认模板读取结果，快速定位问题
  console.log('读取到的模板内容：', html);
  return hbs.compile(html)(data);
}

高频出错点3：Handlebars依赖导入错误

很多开发者会混淆handlebars、hbs、express-handlebars三个包，如果仅用于编译模板而非Express视图层渲染，建议直接使用官方handlebars核心包，避免API不兼容：

安装依赖：npm i handlebars
修正导入：

const Handlebars = require('handlebars');
// 编译逻辑改为
const template = Handlebars.compile(html);
return template(data);

附加优化：Express路由增加错误捕获

避免模板渲染、PDF生成过程中的错误导致服务直接崩溃：

app.get("/generate-pdf", async (req, res, next) => {
  try {
    const htmlContent = await renderTemplate({ name: "test" }, "test");
    console.log("渲染后内容：", htmlContent);
    await generatePDF("test.pdf", htmlContent);
    res.sendFile(path.join(__dirname, "test.pdf"));
  } catch (err) {
    console.error('生成PDF失败：', err);
    res.status(500).send('生成PDF失败');
  }
});

最终排查步骤

查看控制台打印的模板内容，确认是否成功读取到.hbs文件内容，如果为空则检查路径拼写、模板文件存放位置、文件读取权限。
如果模板内容正常但渲染结果为undefined，检查模板语法是否正确，是否使用了未注册的Helper、Partial。
确认依赖安装正确，执行npm list handlebars检查包是否正常安装。

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