pug进去一直服务器不正常，十有八九是模板引擎渲染异常、缓存残留或环境依赖不匹配造成的，按“清缓存查语法验环境看资源”的顺序排查，多数问题能在十分钟内定位。
先分清异常类型再动手
服务器跑不起来和页面渲染出错是两码事，你打开页面看到白屏、500错误、报错信息带pug字样，和服务器直接拒绝连接，排查方向完全不同，前者是pug模板处理环节的问题,后者大概率是进程崩溃或端口被占用。
业内专家指出，超过六成的pug服务器异常都发生在模板编译阶段，而不是服务本身，先看一眼控制台日志，如果错误提示指向某个.pug文件的行号，那基本就是模板语法或数据传递的问题,别急着重启服务器。
pug模板文件修改后不生效的常见原因
这是最让人抓狂的场景：代码改得明明白白，浏览器刷新就是旧页面，很多人在这一步反复重启服务器,其实问题不在服务端逻辑。
缓存机制在捣乱
pug编译后的HTML会被缓存到内存中，开发环境下，你需要确保使用pretty选项并开启热更新，Express框架中，设置app.locals.cache = false只是表面功夫，关键是模板引擎的cache选项要设为false。
app.set('view cache', false);这行代码放在开发环境里能解决大部分“改了没反应”的问题，生产环境则相反，必须开启缓存提升性能,这是另一个话题。
文件监听没生效
用nodemon或pm2启动服务时，默认可能只监听.js文件变化。.pug文件修改后不会触发重启,需要显式配置监听扩展名：
nodemon -e js,pugpm2的话，用pm2 start app.js --watch --ignore-watch="node_modules"，同时确认项目路径没有中文或特殊字符,某些文件系统对这类路径的监听会失效。
pug模板渲染失败原因的系统排查
当pug文件本身有问题，服务器会直接抛错，常见的有三类：缩进错误、标签闭合错误、变量未定义。
缩进和语法是重灾区
pug依赖缩进区分层级，一个多余或缺失的空格就能让整个模板崩溃，报错通常会指向“unexpected token”或“expected indentation”,这类问题用支持pug语法高亮的编辑器能避开大半。
还有个隐蔽问题：混用空格和Tab，pug对这两种缩进方式极为敏感，混用会导致解析错乱，在VS Code中设置"editor.insertSpaces": true能统一为空格。
变量和过滤器问题
模板里用了不存在的变量，pug不会报编译错误，但运行时渲染会抛异常，检查传给模板的数据对象，确保每个#{variable}都有对应的值。.pug文件里如果使用了include或extends引用其他片段，路径写错也会导致编译失败，报错信息可能很隐晦,直接说找不到模块。
服务器资源不足时的pug异常表现
常规检查都做了还不行，就看看机器本身，pug渲染是CPU密集操作，并发量高时，服务器可能长时间无响应,看起来像死机。
用top命令看CPU占用率，如果node进程接近100%，且请求响应极慢，说明模板渲染成了瓶颈，此时优先检查是否有无限循环或递归include某个模板文件循环引入自身,会导致编译过程耗尽内存。
另一个常见资源问题是磁盘空间不足，日志文件、上传文件把分区塞满，pug编译产生的临时文件写不进去，服务就会报“ENOSPC”错误,清理磁盘后问题通常立刻消失。
pug和后端框架的配置协同问题
很多人的pug模板本身没问题，问题出在框架集成上，不同版本组合会有兼容性差异，尤其是express 4.x与pug 2.x、express 5.x与pug 3.x之间的搭配。
渲染引擎声明方式
Express中配置view engine时,写错别名会导致彻底无法渲染：
app.set('view engine', 'pug');确保pug模块实际安装在项目依赖里，而不是全局环境，服务器部署时，npm install --production
如果漏掉了devDependencies中的pug，就会出现“Cannot find module ‘pug’”的报错。
中间件拦截导致的问题
某些请求处理中间件可能提前截断了响应，比如未设置正确的Content-Type，pug渲染后的HTML是text/html，如果中间件改写了响应头，浏览器可能无法正常解析，显示为乱码或直接触发下载行为，症状看起来也像“服务器不正常”。
pug性能优化方案及对比选型
如果资源没瓶颈，模板本身也没问题，但访问量上来后服务器就是扛不住，需要从性能角度优化，pug和其他模板引擎相比,在复杂页面下性能差距可能相当明显。
| 对比项 | pug | ejs | nunjucks |
|---|---|---|---|
| 编译速度 | 中等 | 较快 | 中等偏慢 |
| 语法学习曲线 | 较高（缩进敏感） | 低（近似HTML） | 中等 |
| 调试难度 | 较高 | 低 | 中等 |
| 适合场景 | 大型复杂页面 | 简单页面快速开发 | 需要模板继承的复杂逻辑 |
针对pug本身，主要优化手段是开启视图缓存和预编译模板，生产环境下，将view cache设为true能显著减少重复编译开销，如果项目使用了webpack等构建工具，可以用pug-loader配合pug-html-loader实现模板预编译，运行时只做数据填充，不再进行字符串解析,这在性能敏感的场景下提升显著。
极端情况下的pug异常处理
有个容易忽略的点：项目的pug版本和全局pug命令版本不一致，命令行执行pug --version得到的版本，和项目里npm list显示的可能完全不同，当用全局命令做文件监听或批量编译时，结果可能与预期不同,间接影响服务器运行。
另一个极端场景是pug文件编码问题，从Windows迁移到Linux服务器时，文件编码如果是GBK而非UTF-8，模板中中文会显示为乱码，在某些情况下甚至会导致编译直接失败，用
file命令检查文件编码，统一转换为UTF-8即可。
pug相关常见问题快速解答
pug模板报错“unexpected text”是什么含义？
这个错误几乎总是由未闭合的标签或错误缩进导致，pug对标签的解析依赖缩进和行的起始位置，比如直接在p后另起一行写了文本，却没有正确缩进，就会触发这个报错，检查报错提示的行号，从该行往上排查缩进和标签配对情况,修复后问题会消失。
改完pug文件后浏览器始终显示旧内容，怎么解决？
先按Ctrl+F5强制刷新排除浏览器缓存，无效则检查服务端模板缓存，确认view cache配置为false（开发环境），之后查看启动命令是否监听了.pug文件变化，没有则加上对应参数，最后一步，完全停止node进程，手动删除项目根目录下的cache或tmp目录，重启服务，按照这个顺序操作,多数情况下在第三步就能解决。
有大量相似页面时，pug能支持复用组件吗？
可以，这是pug的核心优势之一，通过mixin（混入）定义可复用的页面模块，比如文章卡片、分页按钮、侧边栏组件，然后在多个模板中引用，配合include和extends实现页面继承，能有效减少重复代码，这种结构不仅方便维护,也让模板文件本身更清晰。
服务器异常这个问题，从根源上说是pug模板的编译链路中某个环节脱节了，排查思路其实很简单，从修改了哪里看起，顺着配置文件、缓存状态、资源占用这三个方向逐一排除，就能定位到具体原因，多数情况下的答案，都藏在模板调试、缓存清理和依赖检查这三件事里，按这几步走完还解决不了的情况，再考虑着手深入分析，看看是不是框架集成层面的兼容性问题，实际操作一遍，每次排查都是一次经验积累,下次遇到类似情况处理起来就更顺手。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/pug%e8%bf%9b%e5%8e%bb%e6%9c%8d%e5%8a%a1%e5%99%a8%e4%b8%80%e7%9b%b4%e4%b8%8d%e6%ad%a3%e5%b8%b8%e6%80%8e%e4%b9%88%e5%8a%9e%ef%bc%8c%e6%80%8e%e4%b9%88%e5%9b%9e%e4%ba%8b/
