使用 VitePress 轻松搭建一个简单的导航站

在日常工作和学习中，我们经常会收集各种有用的网站链接，从开发工具、技术文档到实用的在线服务。随着收藏的网站越来越多，如何高效地管理和快速访问这些资源成了一个问题。

今天我们就来使用 VitePress 搭建一个简洁、美观且高度可定制的个人导航站，让你的常用网站井井有条，随时可达。

导航将基于 GitHub 的开源项目： vitepress-nav-template

预览

在开始之前，可以访问下面的网站预览一下效果：

为什么选择 VitePress？

相比于传统的导航站解决方案，vitepress-nav-template 基于 VitePress 构建，具有以下优势：

  • 轻量快速：基于 Vite 构建，开发体验流畅，构建速度极快
  • 部署简单：静态站点，可轻松部署到 GitHub Pages、Netlify 等平台
  • 响应式设计：支持移动端，随时随地访问你的导航站

不足之处就是数据都保存在一个文件内，编辑时不太直观。

安装

安装 vitepress-nav-template 非常的简单，我们只需要使用 git clone 一下这个项目即可

1
git clone https://github.com/maomao1996/vitepress-nav-template.git my-nav

如果希望使用 GitHub (GitHub Pages) 可以在 GitHub 项目页面上直接点击 Use this template > Create a new repository
然后再 clone 自己的 Repo 到本地

进入文件夹，安装依赖后，即可运行本地预览

1
2
3
4
5
6
7
8
# 进入项目文件夹
cd my-nav

# 安装依赖
pnpm install 

# 运行预览
pnpm dev

vitepress-nav-pnpm-dev.png

第一次运行时会显示一些依赖报错，这并不影响我们的使用，可以忽略。

然后我们访问 http://localhost:8732/ 即可进行预览，默认是首页界面，点击前端导航既可以打开导航页面 http://localhost:8732/nav/

vitepress-nav-prevew.png

访问后可以发现网站已经自带了一些数据，我们需要自己进行修改

更新内容

如果你不熟悉 VitePress ，那么需要先了解一下文件结构

在 VS Code 左侧的资源管理器查看文件，我们需要关注的是 docs 文件夹：

VitePress 会将对应的 filename.md 编译为 filename.html

  • docs/.vitepress/ : 站点配置文件夹
  • docs/nav/ : 导航页的文件夹
  • docs/public/ : 存放图标静态资源
  • docs/index.md : 模板默认的首页内容，test.md 可以直接删除

vitepress-nav-files.png

更改站点数据

在 docs/.vitepress/config.ts 配置文件中包含了站点的基本配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
export default defineConfig({ 
    // ...
    // 修改站点名称
    title: '站点名称',
    // 修改站点描述
    description: '站点的描述',
    
    // ...
    // 站点右上角的 Github 图标与链接
    socialLinks: [{ icon: 'github', link: 'https://github.com/maomao1996/vitepress-nav-template' }],

    // 修改底部的 footer 的信息
    footer: {
      message: '如有转载或 CV 的请标注本站原文地址',
      copyright: 'Copyright © 2019-present maomao',
    },

    /*** 自定义配置 ***/
    // 访客统计数据，我们可以注释掉
    // visitor: {
    //   badgeId: 'maomao1996.vitepress-nav-template',
    // },

    // giscus 评论的设置
    comment: {
        //..
    }

修改顶部导航栏

站点顶部导航的栏的数据保存在 docs/.vitepress/configs/nav.ts

1
2
3
4
5
6
7
8
9
10
import type { DefaultTheme } from 'vitepress'

export const nav: DefaultTheme.Config['nav'] = [
  { text: 'Bookmarks', link: '/' },
  { 
    text: 'O\'s World', 
    link: 'https://ooo.run' 
  },
  // 按照需求修改添加
]

修改导航数据

导航页面的数据都保存在 docs/nav/ 文件夹内，我们需要修改的是 data.ts 内的内容

文件结构

导航数据采用分类结构，每个分类包含标题和导航项目列表：

1
2
3
4
5
6
7
8
export const NAV_DATA: NavData[] = [
  {
    title: '分类标题',
    items: [
      // 导航项目列表
    ]
  }
]

添加新分类

在 NAV_DATA 中添加新的分类对象：

1
2
3
4
5
6
7
8
9
10
11
{
  title: '新分类名称',
  items: [
    { 
        /** 导航 item 1 **/ 
    },
    { 
        /** 导航 item 2 **/ 
    },
  ],
}

添加导航项目

在现有分类的 items 中添加新项目：

1
2
3
4
5
6
{
  icon: 'https://example.com/favicon.ico',  // 外部图标链接
  title: '网站标题',
  desc: '网站描述（可选）',
  link: 'https://example.com',
}

图标设置

  1. 使用外部图标链接

    1
    icon: 'https://example.com/favicon.ico'

  2. 使用本地图标文件

    1
    2
    // 放置在 public/icons/ 目录下
    icon: '/icons/filename.svg'

访问时直接打开导航页面

我们只需要把 docs/nav/ 中文三个文件复制到 docs/ 下面即可

移动文件后，我们需要更新一些导入文件的路径，在 data.ts 将第一行

1
import type { NavLink } from '../.vitepress/theme/types'

修改为

1
import type { NavLink } from './.vitepress/theme/types'

关闭评论

目前评论是使用作者的 giscus 数据，可以在 docs/.vitepress/config.ts 中更换为自己的部分，如何不需要评论可以直接注释掉 comment 部分

1
2
3
4
5
6
// comment: {
//   repo: 'maomao1996/vitepress-nav-template',
//   repoId: 'R_kgDOJC09Jg',
//   category: 'Announcements',
//   categoryId: 'DIC_kwDOJC09Js4Cekn0',
// },

部署至网络

GitHub Pages

项目已经自带了 github pages 部署脚本 .github/workflows/deploy.yml，推送到 Github 时将自动部署，推送静态站点文件至 gh-pages 分支。

如果你的 GitHub Pages 的域名绑定名额已经被其他项目使用，那么可以使用 https://your-project.github.io/project 访问另外的项目的 gh-pages

Cloudflare Pages

如果你不想使用 GitHub 或是更喜欢使用 Cloudflare 的服务，也可以选择部署至 Cloudflare Pages。

下面将介绍使用命令或是手动上传文件进行部署的方式。

创建 Pages 项目

访问 Cloudflare 的 Dashboard，按照下面的步骤操作

  • 首先点击左侧的 计算 (Workers) > Workers 和 Pages
  • 点击 创建 按钮后，选择 Pages，再选择 手动上传
  • 在新的页面设置 项目名称

生成静态资源

在上传资源之前，我们需要先生成导航网站的静态资源，运行下面命令即可

1
pnpm build

网站的静态资源将生成在 dist/ 目录下面，最简单就是手动打包为 zip 然后在部署界面上传，当然这太不优雅了。

部署至 Pages

我们可以使用 Cloudflare 的 wrangler ，只需要执行下面的命令

1
pnpm add -D wrangler@latest

创建部署配置文件，在根文件夹下创建 wrangler.toml，填入下面的内容 

1
2
3
name = "your-project-name"
pages_build_output_dir = "./dist"
compatibility_date = "2025-08-01"

然后运行

1
npx wrangler pages deploy

第一次运行时需要进行认证授权，在浏览器内访问链接后点击授权即可。

然后即可完成部署。

根据命令提示，访问 pages.dev 域名即可查看网站。

绑定自定义域名

在 Cloudflare Dashboard 打开 Workers 和 Pages，再点击 自定义域 即可进行添加。

如果你的域名托管在 Cloudflare ，只需要输入对应的域名即可。