Buffalo模板渲染需路径约定、上下文注入和预编译检查三者配合，缺一即导致r.HTML() panic；template not found错误主因是文件名大小写不符、路径用斜杠而非点号分隔、templates目录位置错误，或未启用app.PrecompileTemplates()提前校验。
Buffalo 的模板渲染不是“写完 HTML 就能跑”，它依赖路径约定、上下文注入和预编译检查三者配合；漏掉任一环，r.HTML() 就会 panic。
template not found 错误怎么快速定位
这是开发期最常遇到的 panic，本质是 r.HTML("users/show") 按约定去 templates/users/show.html（或 templates/users/show/index.html）找文件，但没找到。
- 检查文件名是否全小写：写成
Users/show.html或show.HTML都会失败 - 路径必须用点号分隔，不能用斜杠：
r.HTML("users.show")✅，r.HTML("users/show.html")❌ - 确认
templates/目录存在且在项目根目录下（不是app/templates或actions/templates） - 启动时加
app.PrecompileTemplates()，能在buffalo dev启动阶段就报出缺失文件或语法错误，而不是等第一次访问才 panic
c.Render() 和 c.HTML() 的关键区别
c.HTML() 是裸响应，不走模板引擎，也不注入任何变量；c.Render() 才真正触发 plush 渲染流程，并把传入的数据变成模板里的 .。
Buffalo框架 1.0.1
下载
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
- 错用
c.HTML(200, "<h1>{{ .Name }}</h1>")→ 页面原样输出{{ .Name }}，变量不会被替换 - 正确写法：
c.Render(200, r.HTML("users/show.html"), User{Name: "Alice"})，模板中才能用{{ .Name }} - 结构体字段必须首字母大写（导出），否则 plush 读不到：
Name string✅，name string❌ - 传
map[string]interface{}也行，但 key 必须是 string，且注意拼写一致（"name"和.name要对上）
layout.html 不生效的常见原因
Buffalo 默认查找 templates/layout.html 作为全局布局，但它不会自动套用——必须满足三个条件：
- 必须用
c.Render()，不能跳过它直接写响应体 -
layout.html文件里必须有{{ yield }}（不是{{ .Content }}或{{ yield "main" }}） - 子模板必须用
{{ define "main" }}包裹内容块（名字要和{{ yield }}期望的一致，默认是"main"） - 如果想复用同一份 layout 但换标题，得在 handler 中显式传参：
c.Render(200, r.HTML("users/index.html"), buffalo.Options{"Title": "Users"})，模板里用{{ .Title }}
表单验证失败后如何保留数据重渲染
直接 r.HTML("new.html") 会导致表单清空，因为 POST 数据没进模板上下文。关键不是模板问题，而是上下文没延续。
- 必须在 handler 中把原始数据结构体实例存进 context：
c.Set("user", &u)，其中&u已通过c.Bind()绑定好 - 结构体字段要有
form:"name"tag，比如Name string `form:"name"` - 模板中用
{{ if .FormErrors }}{{ .FormErrors.name }}渲染错误，用{{ .user.Name }}回填值 - 漏掉
c.Set()或没写form:tag，就会丢失数据——这不是渲染失败，是数据根本没传进去
真正容易被忽略的是：Buffalo 的模板系统不维护请求状态，所有“保留”都靠你手动塞数据；.FormErrors 是框架自动塞的，但原始表单值不是。
