express-handlebars注册Partial失败，无法找到header组件求助

我在Express应用里注册Handlebars Partial一直失败，试了各种方案都没用。

我的配置与代码 #

express-handlebars配置代码 #

import { engine } from 'express-handlebars';

// 因为用ES模块，不加这段就跑不起来，具体原理不太清楚
const __filename = new URL(import.meta.url).pathname;
const __dirname = path.dirname(__filename);

app.set('view engine', 'hbs');
app.set('views', './views');
app.engine('hbs', engine({
    extname: '.hbs',
    partialsDir: path.join(__dirname, 'views', 'partials')
}));

项目目录结构 #

布局文件（引入header partial） #

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{title}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
    {{> header }}

    {{{body}}}

</body>
</html>

header Partial内容（放在partials文件夹下） #

<header>
    <p>Welcome back</p>
</header>

报错信息 #

Error: The partial header could not be found
    at Object.invokePartial (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\runtime.js:332:11)
    at Object.invokePartialWrapper [as invokePartial] (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\runtime.js:84:39)
    at Object.eval [as main] (eval at createFunctionContext (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\compiler\javascript-compiler.js:262:23), <anonymous>:13:28)
    at main (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\runtime.js:208:32)
    at ret (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\runtime.js:212:12)
    at ret (C:\Users\sasda\Desktop\websockets\node_modules\handlebars\dist\cjs\handlebars\compiler\compiler.js:519:21)
    at ExpressHandlebars._renderTemplate (C:\Users\sasda\Desktop\websockets\node_modules\express-handlebars\dist\express-handlebars.js:244:16)
    at ExpressHandlebars.<anonymous> (C:\Users\sasda\Desktop\websockets\node_modules\express-handlebars\dist\express-handlebars.js:156:31)
    at Generator.next (<anonymous>)
    at fulfilled (C:\Users\sasda\Desktop\websockets\node_modules\express-handlebars\dist\express-handlebars.js:10:58)

解决步骤 #

1. 检查Partial文件名后缀
   配置里指定了extname: '.hbs'，所以你的header partial必须命名为header.hbs，不能是无后缀或者其他格式，去目录里确认文件名是否正确。

2. 验证Partials目录路径
   把partials路径打印出来，确认是否指向正确的文件夹：

   const partialsPath = path.join(__dirname, 'views', 'partials');
   console.log('Partials目录路径:', partialsPath);
   app.engine('hbs', engine({
       extname: '.hbs',
       partialsDir: partialsPath
   }));
   

   确保打印的路径和你实际的views/partials文件夹完全一致，Windows系统注意路径分隔符的问题。

3. 改用绝对路径设置views目录
   把app.set('views', './views')换成绝对路径，避免模块路径解析出错：

   app.set('views', path.join(__dirname, 'views'));
   

4. 检查依赖版本与兼容性
   可能是express-handlebars版本问题，试试重新安装依赖：

   npm uninstall express-handlebars
   npm install express-handlebars
   

5. 确认Partial调用拼写
   检查布局里的{{> header }}有没有拼写错误，文件名和调用名要完全一致（虽然Windows不区分大小写，但最好统一）。

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