不能用 Gin 的 c.HTML 批量生成静态 HTML 文件,因其仅在运行时响应 HTTP 请求,不支持导出到磁盘;正确做法是绕过 Gin,直接用 Go 标准库 html/template 解析模板、构造数据、执行渲染并写入文件,需注意路径、错误处理、子模板查找及静态资源路径适配。

不能直接用 Gin 的 c.HTML 批量生成静态 HTML 文件——它只在运行时响应请求,不输出磁盘文件。 真正可行的方案是绕过 Gin 的 HTTP 生命周期,直接调用 Go 标准库 html/template 渲染并写入文件。
为什么不能用 router.LoadHTMLGlob + c.HTML 生成静态页
Gin 的模板加载(LoadHTMLGlob)和渲染(c.HTML)是为服务端动态响应设计的:模板被编译进内存、绑定路由、等待 HTTP 请求触发。它没有提供“导出到磁盘”的接口,也没有上下文(*gin.Context)以外的渲染入口。强行模拟 *gin.Context 不仅复杂,还会引入无谓依赖和潜在 panic。
用 html/template 直接渲染到文件(推荐)
这是最轻量、最可控的方式,完全脱离 Gin 运行时。核心步骤就是:解析模板 → 构造数据 → 执行渲染 → 写入文件。
关键点:
-
template.ParseFiles或template.Must(template.New("").ParseGlob("templates/**/*"))加载模板(注意路径是相对于当前工作目录) - 模板中仍可用
{{ .Title }}、{{ range .Items }}等语法,与 Gin 中一致 - 必须手动处理错误,尤其是
tmpl.Execute—— 它不会 panic,但返回error,忽略会导致空文件 - 如果模板用了
{{ define "xxx" }},需用tmpl.Lookup("xxx")获取子模板再执行
示例片段:
tmpl := template.Must(template.ParseGlob("templates/*.html"))
data := struct{ Title string }{"首页"}
f, _ := os.Create("dist/index.html")
defer f.Close()
err := tmpl.Execute(f, data) // 注意:这里不是 c.HTML!
if err != nil {
log.Fatal(err) // 必须检查
}
如何复用 Gin 项目中的模板结构(含 define 和 template)
如果你已用 Gin 的 define/template 做了布局拆分(如 layout.html + post.html),直接复用没问题,但要注意:
- 所有
{{ define }}模板必须在同一个template.Template实例中解析,不能分开ParseFiles - 执行时用
tmpl.Lookup("post.html").Execute(...),而不是直接tmpl.Execute - Gin 的
{{ template "header.html" . }}在纯html/template下完全有效,无需修改 - 路径名必须和
define中声明的一致,比如{{ define "blog/post.html" }}就得用tmpl.Lookup("blog/post.html")
容易被忽略的细节
批量生成时真正卡住人的往往不是逻辑,而是环境一致性:
- 工作目录影响
ParseGlob和os.Create路径——建议用os.MkdirAll("dist", 0755)+ 绝对路径拼接 - 模板里引用的静态资源(如
/static/css/main.css)在离线 HTML 中需改为相对路径(../static/css/main.css),否则浏览器打不开 - Go 的
html/template默认转义,和 Gin 行为一致;但若需插入原始 HTML,要用template.HTML类型字段,不能直接传字符串 - 没有 Gin 的中间件(如日志、恢复 panic),错误只能靠
log.Fatal或显式返回,不适合嵌入长周期服务











