如何在 Golang Gin 框架中利用模板引擎渲染自定义的 404 错误页面-Golang-PHP中文网

gin 默认404页面无法被模板引擎接管，因其defaultwriter在路由未匹配时直接输出纯文本，绕过模板渲染；必须用noroute()注册兜底路由并手动调用c.html(404, "404.html", data)。

如何在 golang gin 框架中利用模板引擎渲染自定义的 404 错误页面

为什么 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", ...) 更可靠且语义清晰。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

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