VitePress 博客搭建 原创

VitePress 博客搭建大体分为 3 步：

1. 安装 VitePress
2. 安装 Teek
3. 安装 VitePress I18n

注意

本文默认您已安装 Node.js 24.15.0 版本和 pnpm 10.33.2 版本。

VitePress

安装

$ pnpm add -D vitepress@1.6.4

注意

本项目使用最新稳定版 VitePress 1.6.4，而不是最新的 VitePress 2.0.0-alpha.xx 版本。

初始化

$ pnpm vitepress init

执行初始化后，将会有如下的配置过程。

T  Welcome to VitePress!
|
o  Where should VitePress initialize the config?
|  ./docs
|
o  Site title:
|  白羽拾光 🕊️
|
o  Site description:
|  拾起光阴落下的羽毛。
|
o  Theme:
|  Default Theme
|
o  Use TypeScript for config and theme files?
|  Yes
|
o  Add VitePress npm scripts to package.json?
|  Yes
|
—  Done! Now run pnpm run docs:dev and start writing.

启动开发环境

$ pnpm docs:dev

编译

$ pnpm docs:build

编译后，会生成 .vitepress/cache 和 .vitepress/dist 文件夹。

启动编译后的项目

$ pnpm docs:preview

是否需要额外安装 Vue？

Vue 默认作为 peer dependency 进行配置，表示 Teek 需要 Vue，但不会自动安装 Teek。

如果打算使用 Vue 组件或 API 进行组件自定义，还应该明确地将 vue 安装为 dependency。

$ pnpm add vue

Teek

安装

$ pnpm install vitepress-theme-teek -D

引入

根据 VitePress 的要求，需要在 .vitepress/theme/index.mts 文件中引入 Teek 主题。如果没有该路径，需要先创建它：

import { defineConfig } from 'vitepress'
import { teekConfig } from './teekConfig.mts'

export default defineConfig({
  extends: teekConfig
})

然后在 .vitepress/theme/teekConfig.mts 文件中配置 Teek 配置加载器：

// .vitepress/teekConfig.mts
import { defineTeekConfig } from "vitepress-theme-teek/config";

// Teek 完整配置：
// https://github.com/Kele-Bingtang/vitepress-theme-teek/blob/main/packages/config/types.ts
export const teekConfig = defineTeekConfig({
  // 是否启用 Teek 主题
  teekTheme: true,
  // 是否启用主题的首页风格（博客风格）
  teekHome: true,
  // 是否启用 VitePress 首页风格
  vpHome: false,
  // 等等
});

更新

Teek 不定期提供新特性或者修复 Bug，届时只需要更新版本号即可：

$ pnpm add vitepress-theme-teek@latest -D

Teek 主题包引用

如果要在 .vitepress/theme/index.ts 中使用 Teek 主题包，则需安装 sass。

$ pnpm add -D sass

@ 配置

安装 Node.js 的 TypeScript 类型声明包。

$ pnpm add -D @types/node

在 tsconfig.json 中添加如下代码，以配置 TS 编辑器。

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["docs/.vitepress/theme/*"]
    }
  }
}

在 config.mts 中添加如下代码，以配置编译选项。

import path from 'path';

const vitePressOptions: UserConfig = {
  vite: {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './theme'),
      }
    },
  },
}

其中，__dirname 获取当前文件所在目录的绝对路径，再拼接 ./theme，即 docs/.vitepress/theme。

因此，编译器在遇到 @ 时，会自动将 @ 路径映射为 docs/.vitepress/theme。

VitePress I18n

国际化插件，在本项目中仅用于搜索栏的翻译。

安装

$ pnpm add -D vitepress-i18n

引入

参考 .vitepress/config.mts 中的配置即可。