Gin 默认404页面无法被模板引擎接管，因其DefaultWriter在路由未匹配时直接输出纯文本，绕过模板渲染；必须用NoRoute()注册兜底路由并手动调用c.HTML(404, "404.html", data)。
为什么 Gin 默认 404 页面无法被模板引擎接管
Gin 的 DefaultWriter 在未匹配路由时直接写入纯文本 "404 page not found"，绕过了你注册的 HTML 模板引擎。这不是配置遗漏，而是 Gin 路由未命中时根本不会进入任何 handler，模板自然没机会执行。
必须显式注册一个“兜底路由”来捕获所有未匹配路径，并手动调用 HTML 方法渲染模板。
- 不能依赖
gin.Default()自动处理 404 —— 它只对已注册路由生效 - 兜底路由必须放在所有其他
GET/POST路由之后，否则会拦截正常请求 - 状态码需显式设为
404，否则默认是200
如何注册全局 404 模板路由
在初始化 gin.Engine 后、启动服务器前，添加一条通配符路由：
router := gin.Default()
router.LoadHTMLFiles("templates/404.html", "templates/base.html")
// ... 其他路由
router.NoRoute(func(c *gin.Context) {
c.HTML(404, "404.html", gin.H{"title": "Page Not Found"})
})
NoRoute() 是 Gin 提供的专用钩子，仅在所有路由均未匹配时触发，比用 router.GET("/*path", ...) 更可靠且语义清晰。
立即学习“go语言免费学习笔记（深入）”；
-
NoRoute()不接受路径参数，也不参与路由树匹配，纯粹是兜底逻辑 - 确保
LoadHTMLFiles()或LoadHTMLGlob()已加载对应模板文件，否则会 panic - 传入的 map 数据可包含动态内容，比如当前 URL：
gin.H{"url": c.Request.URL.Path}
模板中访问 Gin 上下文变量的限制
Gin 模板里不能直接调用 c.Request 或 c.Param() —— 渲染时上下文已脱离 handler 执行栈。所有需要的数据必须提前塞进 gin.H 传入。
常见需求如显示原始请求路径、Referer 或 User-Agent，都得在 NoRoute handler 里手动提取：
router.NoRoute(func(c *gin.Context) {
c.HTML(404, "404.html", gin.H{
"path": c.Request.URL.Path,
"referer": c.GetHeader("Referer"),
"ua": c.GetHeader("User-Agent"),
})
})
- 模板内只能用传入的 key，比如
{{.path}}，不能写{{.Request.URL.Path}} - 如果需要复用某些通用数据（如站点名、CDN 地址），建议封装成函数注入到模板，而非每次重复传
- 避免在
NoRoute中做耗时操作（如 DB 查询），404 是高频错误，性能敏感
静态资源与 404 模板共存时的路径冲突
如果你同时用了 router.Static() 提供前端资源（如 /static/），而用户请求了不存在的 JS 文件，Gin 会先尝试匹配静态文件路径 —— 若失败，才进入 NoRoute。但此时 c.Request.URL.Path 是带前缀的（如 /static/missing.js），可能影响模板逻辑判断。
- 不需要额外处理：只要
NoRoute在Static()之后注册，它就能捕获所有未命中请求 - 若需区分“页面 404”和“资源 404”，可在 handler 中判断路径前缀：
strings.HasPrefix(c.Request.URL.Path, "/static/") - 注意：Gin 的
StaticFS默认返回200+ 空响应体，不是404；只有Static在文件不存在时才会触发NoRoute
真正容易被忽略的是模板中引用的 CSS/JS 路径是否相对正确 —— 404 页面本身加载失败会导致样式错乱，建议用绝对路径或 {{.SiteRoot}} 动态拼接。
