Custom 404 Page
When a user accesses a non-existing path in the EdgeOne Pages project, the platform will provide a standard 404 error page. To ensure user experience consistency, the platform recommends creating a custom 404 page.
Static Site Generator (SSG)
For applications built with static site generators such as Gatsby and Hugo, or those that generate multiple HTML files during build, simply ensure the build output directory contains a
404.html file. At deployment time, Pages will automatically identify this file and return it as the 404 page when no matching path is found for the request.Hugo: Create 404.html in
./layouts/ or the theme directory ./themes/your-theme/layouts/.Gatsby: Create 404.js or 404.tsx in
./src/pages/.Single-Page Application (SPA)
For single-page applications built with modern frontend frameworks like React and Vue, error handling for 404 is normally responsible for client-side routing. Set a "catch-all" or wildcard route in the routing configuration to handle all unmatched paths.
Note:
SPA cannot place 404.html in the output directory root path, which will impact client-side routing configuration.
React: Add one Route with
path="*" at the end of the routing configuration via React-router-dom, the most commonly used routing library in React, and bind it to your custom 404 component.Vue: In the routing configuration array of
Vue Router, add one path: '/:pathMatch(.*)*' routing rule and bind it to your custom 404 component.Server-Side Rendering (SSR)
Pages now support server-side rendering (SSR) mode for the following full-stack frameworks. Since each framework handles 404 webpages differently, the following list shows the configuration method for each framework to ensure your application can display custom 404 pages correctly.
Next.js
Next.js provides flexible ways to handle 404 pages, but since there are two routing mechanisms, Pages Router and App Router, their 404 page setting methods vary slightly.
Pages Router: Create a file named
404.js or 404.tsx under the pages directory. Next.js will compile it into a static HTML file at build time and return this page when no rules matched.App Router: Create a file named
not-found.js or not-found.tsx under the app directory (or in any routing segment). When a user accesses a path with no corresponding page.js file, Next.js will automatically render the latest not-found.js file.Nuxt.js
Create an
error.vue file inside the app/ directory under your project. Nuxt.js will automatically render this page when unable to match any route on the server or client side, or raise error during the rendering process.Astro
Create a
404.astro file under your src/pages/ directory. Astro will automatically identify and use it at build time. When the server receives a request unable to match any page, it will render and return the contents of the 404.astro page, with a 404 status code.React Router (v7+)
Export a component named ErrorBoundary in the root route file (app/root.tsx). The framework leverages React Router's built-in error boundary mechanism to automatically capture all unmatched routes, throw a 404 response, and use the ErrorBoundary you provide to render the error interface.
SvelteKit
Create a
+error.svelte file under your route root directory src/routes/ to create a global 404 page that captures all unmatched routes. You can also place +error.svelte files in any route subdirectory to create local error pages for specific route groups. For example, src/routes/dashboard/+error.svelte will handle all errors under the /dashboard/* path that haven't been captured at deeper levels.