Bootstrap Hugo Docs站点构建失败：出现'render of page failed'错误

问题重现 #

在macOS 13环境下下载Bootstrap源码并完成所有Node依赖安装后，执行命令：

hugo --cleanDestinationDir --printUnusedTemplates

反复出现模板超时错误，核心提示为partial "header" timed out after 30s. This is most likely due to infinite recursion，完整错误日志如下：

ERROR 2023/06/20 11:07:41 render of "page" failed: "/Users/admin/Documents/GitHub/bootstrap_playground/site/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/docs.html:4:7: executing "_default/docs.html" at <partial "header" .>: error calling partial: partial "header" timed out after 30s. This is most likely due to infinite recursion. If this is just a slow template, you can try to increase the 'timeout' config setting.
ERROR 2023/06/20 11:07:41 render of "page" failed: "/Users/admin/Documents/GitHub/bootstrap_playground/site/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/docs.html:4:7: executing "_default/docs.html" at <partial "header" .>: error calling partial: partial "header" timed out after 30s. This is most likely due to infinite recursion. If this is just a slow template, you can try to increase the 'timeout' config setting.
ERROR 2023/06/20 11:07:41 render of "page" failed: "/Users/admin/Documents/GitHub/bootstrap_playground/site/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/docs.html:4:7: executing "_default/docs.html" at <partial "header" .>: error calling partial: partial "header" timed out after 30s. This is most likely due to infinite recursion. If this is just a slow template, you can try to increase the 'timeout' config setting.
ERROR 2023/06/20 11:07:41 render of "page" failed: "/Users/admin/Documents/GitHub/bootstrap_playground/site/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/docs.html:4:7: executing "_default/docs.html" at <partial "header" .>: error calling partial: partial "header" timed out after 30s. This is most likely due to infinite recursion. If this is just a slow template, you can try to increase the 'timeout' config setting.
Total in 119825 ms
Error: error building site: render: failed to render pages: render of "page" failed: "/Users/admin/Documents/GitHub/bootstrap_playground/site/layouts/_default/baseof.html:4:7": execute of template failed: template: _default/404.html:4:7: executing "_default/404.html" at <partial "header" .>: error calling partial: partial "header" timed out after 30s. This is most likely due to infinite recursion. If this is just a slow template, you can try to increase the 'timeout' config setting.

注：相同操作在Replit环境可正常运行，本地环境为npm 9.7.1、Node 18.16.0。

解决方案 #

1. 排查模板无限递归 #

优先检查site/layouts/partials/header.html及它引用的子模板：

• 确认模板中是否存在直接/间接调用自身的逻辑，比如在header模板内再次执行partial "header" .
• 检查模板内的循环、条件逻辑是否会触发无限渲染，比如嵌套的section循环或循环引用的数据结构

2. 临时增加模板超时时间 #

若确认不是递归问题，只是本地环境渲染速度慢，可通过两种方式延长超时：

• 在Hugo配置文件（config.toml/config.yaml）中添加全局配置：

  [params]
    timeout = 60000 # 单位为毫秒，这里设置为60秒
  

• 执行命令时临时指定超时：

  hugo --cleanDestinationDir --printUnusedTemplates --template-timeout 60s
  

3. 同步环境版本 #

Replit运行正常说明本地存在版本差异：

• 对比本地与Replit的Hugo版本，执行hugo version查看，升级/降级到一致版本
• 清理Node依赖缓存后重装：

  rm -rf node_modules package-lock.json
  npm install
  

4. 检查本地文件权限与路径 #

Mac环境下可能存在路径解析或权限问题：

• 修复site/layouts目录权限：

  chmod -R 755 site/layouts
  

• 确认模板内的路径引用为相对路径，避免因系统路径分隔符差异导致的异常

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