Go 的 html/template 执行模板时，即使 Execute 最后返回错误，输出目标里也可能已经有一部分 HTML。官方文档明确说明：执行或写入出错后会停止，但部分结果可能已经写入 io.Writer。因此，err != nil 不代表浏览器什么都没有收到。

普通页面最稳妥的处理方式是先把模板渲染到 bytes.Buffer，成功后再写入 http.ResponseWriter；只有明确需要流式输出时，才接受“已经写出就无法撤回”的边界。

如果页面必须保持完整，就不要直接把 http.ResponseWriter 交给 Execute。先缓冲、检查错误，再提交响应；如果必须流式写出，则把部分响应当成协议设计的一部分。

本文要点：执行错误和写入错误要分开看；missingkey=error 可以尽早暴露数据缺口；缓冲只解决“尚未提交的页面”，不能让已经发出的 HTTP 字节回滚。

为什么 Execute 返回错误时页面已经写了一半

Execute(wr, data) 同时做两件事：读取模板动作并把结果写进 wr。模板前面的静态 HTML 或已经成功求值的字段，可能先后写入 Writer；后面的动作再出错时，执行会停止，但前面的字节不会自动撤回。

这里的错误有两条路径：

• 模板执行路径：字段取值、函数调用或模板动作本身失败；
• 输出路径：Writer 返回错误，例如连接已经断开，写入本身失败。

两者都返回 error，但处理重点不同。前者通常要回到数据准备和模板定义，后者要记录写入位置、连接状态或请求取消。若多个 goroutine 共享同一个 Writer 并发执行模板，输出还可能互相交错，不能把一个 Writer 当成并发安全的拼接器。

先把模板错误与数据缺口暴露出来

map 缺少键时，模板默认可能继续执行并输出 。对于要求完整的页面，可以选择 missingkey=error，让执行在发现缺少键时停止，把问题变成可记录的错误。

package main

import (
    "bytes"
    "fmt"
    "html/template"
)

func renderPage() ([]byte, error) {
    const page = `
{{.Title}}
{{.Summary}}
`

    // missingkey=error 让数据缺口尽早失败，避免把  当成正常页面。
    tmpl, err := template.New("page").Option("missingkey=error").Parse(page)
    if err != nil {
        return nil, fmt.Errorf("解析模板失败: %w", err)
    }

    data := map[string]string{"Title": "模板诊断"}
    var buf bytes.Buffer

    // 先写入内存缓冲区；Execute 失败时，调用方不会拿到半成品响应。
    if err := tmpl.Execute(&buf, data); err != nil {
        return nil, fmt.Errorf("执行模板失败: %w", err)
    }
    return buf.Bytes(), nil
}

上例里 Summary 不存在，错误会在内存阶段返回。函数调用也遵循同一原则：如果自定义模板函数返回错误，Execute 会停止，已经写入缓冲区的内容仍然只存在于内存里，可以整体丢弃。

普通 HTTP 页面怎样避免半页响应

对 HTML 页面，建议把“渲染”和“提交”拆成两个阶段。渲染阶段使用可丢弃的 bytes.Buffer；提交阶段才设置状态并写入 http.ResponseWriter。这样可以把模板错误转成完整的错误响应，而不是在成功页面中间再追加错误文字。

func pageHandler(w http.ResponseWriter, r *http.Request) {
    body, err := renderPage()
    if err != nil {
        // 还没有向 w 写入正文，此时仍可安全返回完整的错误状态。
        http.Error(w, "页面暂时无法生成", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/html; charset=utf-8")
    // 只有渲染成功后才提交正文，避免把半页 HTML 暴露给客户端。
    if _, err := w.Write(body); err != nil {
        // 这里属于 Writer/连接错误，响应可能已经发出一部分，只记录即可。
        log.Printf("写入页面失败: %v", err)
    }
}

如果希望让状态码也更可控，可以在 w.Write 前显式调用 w.WriteHeader；但一旦开始写响应，状态和正文都不能像内存缓冲一样回滚。这里的缓冲不是性能优化，而是把错误发生点放在不可回滚边界之前。

必须流式输出时，怎样处理不可回滚的部分结果

有些场景确实需要边生成边发送，例如长连接上的渐进式 HTML 或持续输出的结果。此时直接执行到 Writer 可以接受，但要把约束写进接口设计：不要在已经写出的页面后面追加一个看似完整的错误页；记录错误并停止继续输出，客户端通过连接关闭、协议标记或业务状态识别未完成结果。

func streamPage(w http.ResponseWriter, tmpl *template.Template, data any) {
    // 流式模式主动接受部分输出不可撤回，先声明这是设计边界。
    if err := tmpl.Execute(w, data); err != nil {
        // 不再追加一段 HTML，避免把半页内容伪装成完整页面。
        log.Printf("流式模板执行中止: %v", err)
        return
    }
}

选择可以用下面的判断快速落地：

常见追问

Execute 返回错误后，能不能继续复用同一个模板？

模板本身可以安全地并行执行，但每次执行都应使用独立的 Writer；是否复用模板和是否复用输出目标是两件事。共享同一个 Writer 会带来交错输出风险。

把错误 HTML 写到 ResponseWriter 能修复半页吗？

不能。错误 HTML 只会继续追加字节，无法删除已经发出的内容。普通页面应在提交响应前完成渲染，流式页面则应设计明确的未完成信号。

missingkey=error 能解决所有 Execute 错误吗？

不能。它只针对 map 键缺失这一类数据访问行为；模板函数错误、转义语义错误和 Writer 写入错误仍需分别处理。

结论：看到“模板执行部分写出后返回错误”，先不要把问题归结为模板引擎随机丢数据。先判断错误发生在模板求值还是 Writer，再看响应是否允许半成品。对普通 HTTP 页面，bytes.Buffer + 成功后提交 是最清晰的边界；对流式输出，则必须把不可回滚的部分结果当成协议的一部分。