自定义 404 页面
当用户访问 EdgeOne Pages 项目中不存在的路径时,平台将提供一个标准的 404 错误页面。为确保用户体验的一致性,平台建议您创建自定义 404 页面。
静态站点生成器(SSG)
对于使用 Gatsby、Hugo 等静态站点生成器构建的应用,或在构建时生成多个 HTML 文件的应用,只需确保构建输出目录中有
404.html 文件,Pages 部署时将自动识别此文件,并在请求未匹配到任何路径时将其作为 404 页面返回。
Hugo:在
./layouts/ 或主题目录下的 ./themes/your-theme/layouts/ 创建 404.html。Gatsby:在
./src/pages/ 创建 404.js 或 404.tsx。
单页应用 (SPA)
对于使用 React、Vue 等现代前端框架构建的单页应用,404 错误处理通常由客户端路由负责。在路由配置中设置一个“捕获所有”或通配符路由,即可处理所有未匹配到的路径。
注意:
单页应用不能在输出目录根路径下放置 404.html,会影响客户端的路由配置。
React:通过 React 中最常用的路由库
react-router-dom 在路由配置的最后添加一个 path="*" 的 Route,并将其 element 指向您的自定义 404 组件。Vue:在
Vue Router 的路由配置数组中,添加一个 path: '/:pathMatch(.*)*' 的路由规则,并将其 component 指向您的自定义 404 组件。
服务端渲染 (SSR)
Pages 目前已支持下列全栈框架的服务端渲染 (SSR) 模式。由于各框架处理 404 页面的机制不尽相同,下面列出了每个框架的配置方法,以确保您的应用能正确展示自定义 404 页面。
Next.js
Next.js 提供了灵活的方式来处理 404 页面,但由于存在 Pages Router 和 App Router 两种路由机制,其 404 页面的配置方式略有不同。
Pages Router:在
pages 目录下创建一个名为 404.js 或 404.tsx 的文件。Next.js 会在构建时将其编译成一个静态 HTML 文件,并在任何未匹配的路由请求时返回该页面。App Router:在
app 目录下(或任何路由段中)创建一个名为 not-found.js 或 not-found.tsx 的文件。当用户访问的路径没有对应的 page.js 文件时,Next.js 会自动渲染最近的 not-found.js 文件。
Nuxt.js
在您的项目下的 app/ 目录里面创建一个
error.vue 文件。当 Nuxt.js 在服务端或客户端无法匹配到任何路由,或在渲染过程中抛出错误时,将自动渲染此页面。
Astro
在您的 src/pages/ 目录下创建一个
404.astro 文件。Astro 会在构建时自动识别并使用它。当服务器收到一个无法匹配任何页面的请求时,会渲染并返回 404.astro 页面的内容,并附带 404 状态码。
React Router (v7+)
在根路由文件 (app/root.tsx) 中导出一个名为 ErrorBoundary 的组件。框架会利用 React Router 的内置错误边界机制自动捕获所有未匹配的路由,抛出一个 404 响应,并使用您提供的 ErrorBoundary 来渲染错误界面。
SvelteKit
在您的路由根目录 src/routes/ 下创建一个
+error.svelte 文件,即可创建一个能捕获所有未匹配路由的全局 404 页面。您还可以在任何路由子目录中放置 +error.svelte 文件,以为特定路由组创建局部的错误页面。例如,src/routes/dashboard/+error.svelte 将会处理所有 /dashboard/* 路径下发生的、且未被更深层级捕获的错误。