Golang Fiber使用Layout渲染指定模板失败问题求助

问题重现 #

项目目录结构如下：

├── Main Folder
   ├── cmd
        └── main.go
   ├── controllers
   ├── models
   ├── views
        └── partials
            └── layout.html
        ├── index.html
        ├── dashboard.html
        └── login.html
   └── public
        └── sample.png

使用Go 1.19 + Fiber v2 + github.com/gofiber/template/html模板引擎，尝试用layout.html作为统一布局渲染多个模板时，出现两个问题：

1. 渲染dashboard页面时，始终显示login.html的内容（总是加载最后一个HTML文件）
2. 控制台报错：template: "partials/layout" is an incomplete or empty template

相关代码：

• layout.html

<!DOCTYPE html>
<html lang="en">
<head>
</head>
<body>
    <h1>Loaded from Layout</h1>
  {{ template . }}
</body>
</html>

• dashboard.html

{{ define "dashboard" }}
    <h1>Dashboard</h1>
{{ end }}

• login.html

{{ define "login" }}
    <h1>Login</h1>
{{ end }}

• Dashboard控制器

func Dashboard(c *fiber.Ctx) error {
    return c.Render("dashboard", fiber.Map{
        "title": "Login | Selectify Admin",
    }, "partials/layout")
}

• main.go模板配置

template_engine := html.New(
    "./views",
    ".html",
)

app := fiber.New(fiber.Config{
    Views: template_engine,
    ErrorHandler: func(c *fiber.Ctx, err error) error {
        return utils.HandleError(c, err)
    },
})

问题原因 #

1. 模板命名空间冲突：使用{{ define "模板名" }}定义的模板会被注册到全局模板命名空间，Fiber加载所有.html文件后，最后一个定义的模板会被优先匹配，导致login内容覆盖dashboard。
2. Layout模板引用错误：layout.html中的{{ template . }}写法错误，此处的.是渲染时传递的fiber.Map数据，并非模板名称，导致无法找到有效模板，触发"不完整/空模板"错误。

解决方案 #

步骤1：修改Layout模板的引用逻辑 #

将layout.html中的{{ template . }}替换为{{ template .TemplateName . }}，Fiber会自动将c.Render第一个参数（即要渲染的子模板名）存入.TemplateName变量，实现动态加载指定子模板：

<!DOCTYPE html>
<html lang="en">
<head>
    <title>{{ .title }}</title> <!-- 可直接使用传递的变量 -->
</head>
<body>
    <h1>Loaded from Layout</h1>
    {{ template .TemplateName . }}
</body>
</html>

步骤2：调整子模板结构，移除全局定义 #

删除dashboard.html和login.html中的{{ define }}包裹，直接编写页面内容，避免全局命名空间冲突：

• 修改后的dashboard.html

<h1>Dashboard</h1>

• 修改后的login.html

<h1>Login</h1>

步骤3（可选）：开发环境开启模板自动重载 #

在main.go中为模板引擎开启自动重载，修改模板后无需重启应用：

template_engine := html.New(
    "./views",
    ".html",
)
// 开发环境启用，生产环境建议关闭
template_engine.Reload(true)

验证效果 #

保持控制器代码不变，重新运行项目：

• 访问Dashboard路由，页面会显示Layout的内容 + Dashboard的标题
• 访问Login路由，页面会显示Layout的内容 + Login的标题
• 控制台不再出现模板错误

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