Error Pages
简介
错误页面组件集合，提供常见HTTP错误状态码的用户友好页面。通过统一的设计风格和清晰的信息传达，帮助用户理解错误原因并提供解决方案。
组件特性：
- 🎨 设计统一 - 所有错误页面采用一致的设计风格
- 🌐 多种错误类型 - 支持404、403、500、503等常见错误
- 🔧 调试友好 - 可选的调试信息显示，便于开发和问题排查
- 📱 响应式设计 - 适配不同屏幕尺寸
- 🎯 用户引导 - 提供有用的操作建议和导航链接
基础用法
使用404错误页面的最简单示例：
基础的404错误页面示例
404
页面未找到
抱歉，您要找的页面不存在或已被移动。
路径：/cosy-ui/zh-cn/courses/components/error-pages/
如果您认为这是一个错误，请联系网站管理员
---
/**
* @component Error404.Basic
*
* @description
* 基础的404错误页面示例，展示最简单的404错误页面用法。
*/
import { Error404 } from '@coffic/cosy-ui';
---
<Error404 />
错误页面类型
403 禁止访问
用于显示用户无权限访问资源的提示：
基础的403禁止访问错误页面示例
---
/**
* @component Error403.Basic
*
* @description
* 基础的403禁止访问错误页面示例。
*/
import { Error403 } from '@coffic/cosy-ui';
---
<Error403 />
500 服务器内部错误
用于显示服务器出现内部错误的提示：
基础的500服务器内部错误页面示例
500
服务器内部错误
服务器遇到了一个内部错误，无法完成您的请求。
路径：/cosy-ui/zh-cn/courses/components/error-pages/
您可以尝试：
- • 刷新页面
- • 几分钟后重试
- • 检查您的网络连接
- • 联系技术支持
如果问题持续存在，请联系我们的技术支持团队
---
/**
* @component Error500.Basic
*
* @description
* 基础的500服务器内部错误页面示例。
*/
import { Error500 } from '@coffic/cosy-ui';
---
<Error500 />
503 服务不可用
用于显示服务临时不可用的提示，特别适用于维护模式：
503服务不可用错误页面的维护模式示例
---
/**
* @component Error503.Maintenance
*
* @description
* 503服务不可用错误页面的维护模式示例，展示系统维护时的页面。
*/
import { Error503 } from '@coffic/cosy-ui';
---
<Error503
maintenanceMode={true}
estimatedRecovery="2024-12-25 10:00"
statusPageUrl="https://status.example.com"
debugKVs={{
reason: '系统升级',
startTime: '2024-12-25 08:00',
version: 'v2.1.0',
}}
/>
通用错误页面
使用 ErrorPage 组件可以根据错误码自动选择合适的错误页面：
---
import { ErrorPage } from '@coffic/cosy-ui';
---
<!-- 根据错误码自动选择页面 -->
<ErrorPage errorCode={404} />
<ErrorPage errorCode={403} loginUrl="/login" />
<ErrorPage errorCode={500} supportUrl="/support" />
<ErrorPage errorCode={503} maintenanceMode={true} />自定义样式
通过class属性自定义错误页面的样式外观：
展示如何自定义错误页面的样式外观
404
页面未找到
抱歉，您要找的页面不存在或已被移动。
路径：/cosy-ui/zh-cn/courses/components/error-pages/
调试信息
customization:
自定义渐变背景
style:
紫色到粉色渐变
note:
这是一个自定义样式的示例
如果您认为这是一个错误，请联系网站管理员
---
/**
* @component ErrorPage.CustomStyle
*
* @description
* 错误页面的自定义样式示例，展示如何通过class属性自定义错误页面的样式。
*/
import { Error404 } from '@coffic/cosy-ui';
---
<div
class="cosy:bg-gradient-to-br cosy:from-purple-50 cosy:to-pink-50 cosy:dark:from-purple-900/20 cosy:dark:to-pink-900/20 cosy:p-8 cosy:rounded-xl">
<Error404
debugKVs={{
customization: '自定义渐变背景',
style: '紫色到粉色渐变',
note: '这是一个自定义样式的示例',
}}
/>
</div>
错误页面展示
查看所有错误页面类型的综合展示：
展示所有错误页面类型的综合示例
错误页面展示
以下是不同HTTP错误状态码对应的错误页面
404 - 页面未找到
404
页面未找到
抱歉，您要找的页面不存在或已被移动。
路径：/cosy-ui/zh-cn/courses/components/error-pages/
调试信息
example:
demo
如果您认为这是一个错误，请联系网站管理员
403 - 禁止访问
500 - 服务器内部错误
503 - 服务不可用
---
/**
* @component ErrorPage.Showcase
*
* @description
* 展示所有错误页面的组件示例，用于演示和测试不同类型的错误页面。
*/
import { ErrorPage } from '@coffic/cosy-ui';
import { Container, Stack } from '@coffic/cosy-ui';
---
<Container size="lg" padding="lg">
<Stack gap="xl">
<div class="cosy:text-center cosy:mb-8">
<h1 class="cosy:text-3xl cosy:font-bold cosy:mb-4">错误页面展示</h1>
<p class="cosy:text-base-content/70">
以下是不同HTTP错误状态码对应的错误页面
</p>
</div>
<!-- 404错误 -->
<section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
<h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
404 - 页面未找到
</h2>
<ErrorPage errorCode={404} debugKVs={{ example: 'demo' }} />
</section>
<!-- 403错误 -->
<section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
<h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">403 - 禁止访问</h2>
<ErrorPage
errorCode={403}
loginUrl="/login"
contactUrl="/contact"
debugKVs={{ requiredRole: 'admin', currentRole: 'user' }}
/>
</section>
<!-- 500错误 -->
<section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
<h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
500 - 服务器内部错误
</h2>
<ErrorPage
errorCode={500}
supportUrl="/support"
statusPageUrl="/status"
debugKVs={{ errorId: 'ERR_2024_001', serverInfo: 'Server-01' }}
/>
</section>
<!-- 503错误 -->
<section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
<h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
503 - 服务不可用
</h2>
<ErrorPage
errorCode={503}
maintenanceMode={true}
estimatedRecovery="2024-12-25 10:00"
statusPageUrl="/status"
notificationUrl="/notifications"
debugKVs={{ reason: '系统升级', startTime: '2024-12-25 08:00' }}
/>
</section>
</Stack>
</Container>
高级用法
添加调试信息
所有错误页面都支持添加调试信息，便于开发和问题排查：
<ErrorPage
errorCode={404}
debugKVs={{
reason: '路由未匹配',
requestedPath: '/some/path',
timestamp: new Date().toISOString(),
requestId: 'REQ_2024_001',
}}
/>维护模式配置
对于503错误，可以配置详细的维护信息：
<ErrorPage
errorCode={503}
maintenanceMode={true}
estimatedRecovery="2024-12-25 10:00"
statusPageUrl="/status"
notificationUrl="/notifications"
debugKVs={{
reason: '系统升级',
version: 'v2.1.0',
startTime: '2024-12-25 08:00',
}}
/>权限错误配置
对于403错误，可以提供登录和联系链接：
<ErrorPage
errorCode={403}
loginUrl="/login"
contactUrl="/contact"
debugKVs={{
requiredRole: 'admin',
currentRole: 'user',
resource: '/admin/dashboard',
}}
/>Props 参考
ErrorPage Props
| 属性 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
errorCode | number | ✅ | - | HTTP错误状态码 (404, 403, 500, 503等) |
debugKVs | Record<string, string> | ❌ | {} | 调试信息键值对，用于开发和调试 |
loginUrl | string | ❌ | - | 登录页面URL (适用于403错误) |
contactUrl | string | ❌ | - | 联系页面URL |
supportUrl | string | ❌ | - | 技术支持页面URL (适用于500错误) |
statusPageUrl | string | ❌ | - | 系统状态页面URL |
notificationUrl | string | ❌ | - | 通知订阅页面URL (适用于503错误) |
maintenanceMode | boolean | ❌ | false | 是否为维护模式 (适用于503错误) |
estimatedRecovery | string | ❌ | - | 预期恢复时间 (适用于503错误) |
个别错误页面 Props
每个具体的错误页面组件都有对应的props，详见各组件的JSDoc注释。
最佳实践
-
使用ErrorPage组件 - 推荐使用
ErrorPage而不是个别的错误页面组件，更灵活且易于维护 -
提供有用信息 - 合理使用
debugKVs提供调试信息，但避免在生产环境中泄露敏感信息 -
引导用户操作 - 根据错误类型提供相应的操作链接：
- 403错误：提供登录链接和联系方式
- 500错误：提供技术支持和状态页面链接
- 503错误：提供维护信息和通知订阅
-
维护友好 - 对于503错误，提供详细的维护信息和预期恢复时间
-
响应式考虑 - 确保错误页面在各种设备上都有良好的显示效果
样式定制
所有错误页面组件都遵循cosy-ui的样式规范：
- 使用daisyUI类作为主要样式基础
- Tailwind CSS类需要添加
cosy:前缀 - 支持响应式设计，适配各种屏幕尺寸
- 完整支持暗色模式切换