如何配置Gin Gonic模板引擎不剥离HTML注释

问题场景 #

使用Gin Gonic框架时，模板文件里的HTML注释（比如<!-- 多行注释内容 -->）会被自动剥离，返回的响应中看不到这些注释。尝试用模板常量{{"<!-- 注释内容 -->"}}输出时，注释标签还会被HTML转义成<!-- 注释内容 -->，无法正常显示为HTML注释。

示例模板文件/static/templates/mytemplate.html：

<!DOCTYPE html>
<html lang="de">
<body>
<!--
these lines are missing in the output
-->
Hello World
</body>
</html>

处理器代码：

func NewRouter() *gin.Engine {
    router := gin.Default()
    // ... 默认方式加载模板 ...
    router.GET("/foo", fooHandler)
    return router
}

func fooHandler(c *gin.Context) {
    c.HTML(http.StatusOK, "static/templates/mytemplate.html", gin.H{
        "name": "World",
    })
}

解决方法 #

Gin底层依赖Go标准库的html/template，该库默认会移除HTML注释。要保留注释，需要在创建模板时设置comment选项：

1. 手动创建模板并配置注释选项 #

替换默认的模板加载方式，手动创建模板实例并开启保留注释的选项：

func NewRouter() *gin.Engine {
    router := gin.Default()
    
    // 创建模板并设置保留HTML注释的选项
    tmpl, err := template.New("").
        SetDelims("{{", "}}"). // 保持Gin默认的模板分隔符
        Option("comment").     // 开启保留HTML注释
        ParseFiles("static/templates/mytemplate.html")
    if err != nil {
        panic(err) // 实际项目中建议做优雅的错误处理
    }
    
    // 将自定义模板设置到Gin引擎中
    router.SetHTMLTemplate(tmpl)
    
    router.GET("/foo", fooHandler)
    return router
}

设置Option("comment")后，模板中的HTML注释会被原样保留在最终输出里。

2. 解决模板常量转义问题（可选） #

如果需要通过模板变量输出HTML注释，避免转义可以给模板注册safeHTML函数：

func NewRouter() *gin.Engine {
    router := gin.Default()
    
    // 注册安全输出HTML的函数
    funcMap := template.FuncMap{
        "safeHTML": template.HTML,
    }
    
    tmpl, err := template.New("").
        SetDelims("{{", "}}").
        Funcs(funcMap).
        Option("comment").
        ParseFiles("static/templates/mytemplate.html")
    if err != nil {
        panic(err)
    }
    
    router.SetHTMLTemplate(tmpl)
    return router
}

然后在模板中使用：

{{safeHTML "<!-- 这是通过模板变量输出的注释 -->"}}

内容的提问来源于stack exchange，提问作者koks der drache