Caddy服务器中错误处理模板的使用技巧

2025-04-30 04:27:03作者：幸俭卉

前言

在使用Caddy服务器时，优雅地处理错误页面是提升用户体验的重要环节。本文将详细介绍如何在Caddy的handle_errors模块中结合templates模块，实现动态错误页面的渲染。

错误处理模板的基本配置

在Caddy配置文件中，我们可以通过handle_errors模块来定义错误处理流程。一个典型的配置示例如下：

handle_errors {
    root * /usr/share/caddy
    templates
    file_server

    @favicon path /favicon.ico
    file_server @favicon

    rewrite * /{err.status_code}.html
    try_files {path} /error.html
}

这段配置实现了以下功能：

设置错误页面的根目录
启用模板渲染功能
配置文件服务器
单独处理favicon请求
根据错误状态码重写URL
尝试查找对应的错误页面文件

模板变量访问技巧

最初尝试在模板中直接使用{{ err.status_code }}这样的变量会失败，因为错误上下文在模板中的访问方式有所不同。正确的做法是使用ph（placeholder）函数来访问错误信息。

一个完整的错误模板示例：

<html lang="zh">
<head>
    <title>{{ ph "http.error.status_code" }} {{ ph "http.error.status_text" }}</title>
    <link rel="icon" type="image/x-icon" href="/favicon.ico">
</head>
<body>
    <h1>{{ ph "http.error.status_code" }} {{ ph "http.error.status_text" }}</h1>
    <p>访问 {{ .OriginalReq.URL }} 时发生错误</p>
    <p>请检查URL是否正确，或稍后再试</p>
</body>
</html>

可用模板变量详解

在错误处理模板中，可以通过以下方式获取相关信息：

错误状态信息：
- {{ ph "http.error.status_code" }} - HTTP状态码（如404、500等）
- {{ ph "http.error.status_text" }} - 状态文本（如"Not Found"）
请求信息：
- {{ .OriginalReq.URL }} - 原始请求的URL
- {{ .OriginalReq.Method }} - 原始请求方法（GET、POST等）
其他上下文信息：
- 可以通过标准模板函数获取时间、环境变量等信息

高级用法

根据不同状态码显示不同内容：

{{ if eq (ph "http.error.status_code") "404" }}
<p>您访问的页面不存在</p>
{{ else if eq (ph "http.error.status_code") "500" }}
<p>服务器内部错误，请联系管理员</p>
{{ end }}

多语言支持：可以通过判断请求头中的Accept-Language来实现简单的多语言错误页面。
记录错误日志：虽然模板本身不能直接写日志，但可以通过自定义模板函数将错误信息传递给外部系统。

最佳实践建议

保持错误页面简洁明了，提供有用的信息
为常见错误状态码（如404、500）设计专门的页面
确保错误页面也遵循网站的整体风格
考虑在错误页面提供导航回首页的链接
对于API请求，可以考虑返回JSON格式的错误信息

通过合理配置Caddy的handle_errors和templates模块，可以大大提升网站在错误情况下的用户体验。本文介绍的方法既保持了配置的简洁性，又提供了足够的灵活性来满足各种需求。

caddy

caddyserver/caddy: 是一个用于自动部署和配置 HTTPS 的服务器软件，可以用于快速部署静态网站和 Web 应用程序，支持 Let\'s Encrypt 的免费 SSL 证书。

项目地址：https://gitcode.com/GitHub_Trending/ca/caddy

登录后查看全文

项目优选

收起

RuoYi-Vue3

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统

旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！

240

283

ShopXO开源商城

🔥🔥🔥ShopXO企业级免费开源商城系统，可视化DIY拖拽装修、包含PC、H5、多端小程序(微信+支付宝+百度+头条&抖音+QQ+快手)、APP、多仓库、多商户、多门店、IM客服、进销存，遵循MIT开源协议发布、基于ThinkPHP8框架研发

JavaScript

UAVS

智能无人机路径规划仿真系统是一个具有操作控制精细、平台整合性强、全方向模型建立与应用自动化特点的软件。它以A、B两国在C区开展无人机战争为背景，该系统的核心功能是通过仿真平台规划无人机航线，并进行验证输出，数据可导入真实无人机，使其按照规定路线精准抵达战场任一位置，支持多人多设备编队联合行动。

JavaScript

nop-entropy

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

Java

vue-devui

基于全新 DevUI Design 设计体系的 Vue3 组件库，面向研发工具的开源前端解决方案。

为仓颉编程语言开发者打造活跃、开放、高质量的社区环境

Markdown

1.07 K

Cangjie-Examples

本仓将收集和展示高质量的仓颉示例代码，欢迎大家投稿，让全世界看到您的妙趣设计，也让更多人通过您的编码理解和喜爱仓颉语言。

Cangjie

331

1.07 K

Caddy服务器中错误处理模板的使用技巧

前言

错误处理模板的基本配置

模板变量访问技巧

可用模板变量详解

高级用法

最佳实践建议

热门内容推荐

最新内容推荐

项目优选

Caddy服务器中错误处理模板的使用技巧

前言

错误处理模板的基本配置

模板变量访问技巧

可用模板变量详解

高级用法

最佳实践建议

相关内容推荐

热门内容推荐

最新内容推荐

项目优选