2025-04-16 teek teek 4287 字 24 分钟 -- 次

自定义404页面

最后更新于: 2026-06-27 15:38:29

自定义404页面

背景

逛掘金发现了一个很酷的 404 页面，于是想在自己的博客也搞一个，正好 VitePress 也支持自定义 404 页面的内容，可以根据官方提供的not-found插槽去配置即可，在自定义的 docs/.vitepress/theme/index.ts 文件中去配置就行。

版权

警告

本着开源共享、共同学习的精神：

本文是在《Hyde Blog》博主的《自定义404》文章基础上增加了一些自己的实际操作记录和修改，内容依旧属于原作者所有。转载无需和我联系，但请注明文章来源。如果侵权之处，请联系博主进行删除，谢谢。

原始作者：《海拥》

环境

2025.4.14(已解决)

警告

次配置适用于Teek@1.0.2-2025.4.10版本（其它版本可自行测试）。

提示

自己开源的《vitepress-theme-teek-one-public》网站模板。

此模板是在《Young Kbt blog》大佬开源项目《vitepress-theme-teek 》基础上修改为自己的风格而成，感谢大佬开发得主题，大佬威武。❤️❤️

1、安装依赖

pnpm npm yarn bun

1pnpm add -D parallax-js

1npm add -D parallax-js

1yarn add -D parallax-js

1bun add -D parallax-js

2、新建组件

在 docs/.vitepress/theme/components 目录下新建 NotFound.vue 文件，内容如下：

NotFound.vue文件内容：

3、注册组件

在docs/.vitepress/theme/index.ts中注册组件

 1import { h } from "vue";
 2import DefaultTheme from "vitepress/theme";
 3import NotFound from "./components/NotFound.vue"; // 导入404组件
 4
 5export default {
 6  // 自定义布局配置
 7  Layout: () => {
 8    const props = {};
 9    // 获取 frontmatter
10    const { frontmatter } = useData();
11
12    // 添加自定义 class
13    if (frontmatter.value?.layoutClass) {
14      props.class = frontmatter.value.layoutClass;
15    }
16    return h(DefaultTheme.Layout, props, {
17      // 自定义文档底部
18      "doc-after": () => h(siteFooter),
19      // 自定义404页面内容
20      "not-found": () => h(NotFound), 
21    });
22  },
23};

自己实际`docs/.vitepress/theme/index.ts`配置内容：

4、测试

运行项目，随便输入一个不存在的url：

https://onedayxyy.cn/xx

测试结束。

扩展

原作者文档

https://juejin.cn/post/7474038290216779788?searchId=20250414011044ECD152E18DDFB55D0E97

在自定义的theme/index.js文件中去配置就行。

 1import { h } from "vue";
 2import DefaultTheme from "vitepress/theme";
 3import NotFound from "./components/404.vue";
 4
 5export default {
 6  // 自定义布局配置
 7  Layout: () => {
 8    const props = {};
 9    // 获取 frontmatter
10    const { frontmatter } = useData();
11
12    // 添加自定义 class
13    if (frontmatter.value?.layoutClass) {
14      props.class = frontmatter.value.layoutClass;
15    }
16    return h(DefaultTheme.Layout, props, {
17      // 自定义文档底部
18      "doc-after": () => h(siteFooter),
19      // 自定义404页面内容
20      "not-found": () => h(NotFound),
21    });
22  },
23};

404.vue 页面

1<template>
2  <div class="not-found">
3    <h1>404</h1>
4    <p>哎呀，您访问的页面不存在！</p>
5    <a href="/404.html" target="_self">返回首页</a>
6  </div>
7</template>