Express中Pug模板未渲染反而显示HTML代码的原因排查

这种时好时坏的渲染问题确实让人头疼——毕竟不是持续复现的bug，排查起来得盯着一些容易被忽略的细节。结合你给出的res.render代码，我整理了几个最可能的诱因：

• 响应头Content-Type异常
  这是HTML被当成纯文本显示的最常见原因。如果Express偶尔没能正确设置Content-Type: text/html，浏览器就会把编译后的HTML代码直接当成普通文本展示。这种情况可能是路由处理环节（比如异步回调、错误捕获逻辑）不小心覆盖了响应头，或是某些中间件干扰了头信息的设置。建议下次出现问题前，在res.render后加一行调试代码：

  console.log('响应头Content-Type:', res.get('Content-Type'));
  

  正常情况下应该输出text/html; charset=utf-8，如果不是，就顺着响应头的修改链路找问题。

• 模板引擎配置的临时失效
  你肯定已经设置了app.set('view engine', 'pug')和views目录路径，但可能因为文件系统的临时波动（比如模板文件读取权限变化、磁盘IO卡顿），导致Express偶尔无法加载Pug编译器， fallback到直接返回编译后的HTML文本。另外要确认模板文件的扩展名是严格的.pug，如果编辑器自动保存成.html，也会出现偶尔的渲染异常。

• 异步数据查询的不稳定
  你的res.render依赖result[0]，说明数据来自异步查询（比如数据库）。如果查询偶尔返回空结果（比如数据库连接临时中断、查询超时），result[0]会变成undefined，触发Pug模板的渲染错误。如果错误处理中间件没正确捕获，就可能返回未完全编译的内容或错误文本。建议在渲染前增加数据校验：

  if (!result || result.length === 0) {
    return res.status(500).send('数据查询失败，请稍后重试');
  }
  res.render('main', {name:result[0].name, surname:result[0].surname, age:result[0].age});
  

• 模板缓存或编译的问题
  开发环境下Express默认不缓存模板，但如果手动开启了app.set('view cache', true)，或使用了第三方缓存工具，可能导致修改后的模板没被重新编译，偶尔返回旧的异常结果。另外，Pug模板里的动态语法（比如条件渲染、循环）如果遇到异常变量值，也会触发编译失败。可以尝试重启服务清除缓存，或在模板里增加变量存在性判断。

• 中间件顺序冲突
  检查中间件顺序：如果express.static静态文件中间件放在了路由之前，而你的main.pug不小心存放在静态目录里，偶尔会被静态中间件直接返回原始文件，跳过Pug渲染。确保路由中间件在静态中间件之后，或把模板文件移出静态目录。

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