从在线文档崩溃说起-我的前端知识管理系统搭建之路

写在前面

欢迎大家 🌟star 、fork

github.com/zhanglkx/Fr...

从在线文档崩溃说起：我的前端知识管理系统搭建之路

那天早上九点，我照常打开电脑准备查看昨晚整理的 React Hooks 笔记。输入网址，回车，然后...白屏。

刷新，继续白屏。

换浏览器，清缓存，关梯子，开梯子...依然白屏。

我开始有点慌了。那份笔记昨晚写到凌晨一点，详细记录了 useEffect 的各种使用场景和坑，还配了好几个实战案例。要是丢了，我得哭死。

赶紧翻手机看看是不是只有我这样，结果一搜发现整个微博都在骂某云文档服务挂了。有人说数据还在，有人说部分文档打不开，还有人直接说"再也不信任在线服务了"。

我当时心里就一个念头：得，是时候自己搞一套了。

为什么不再依赖在线文档？

说实话，这已经不是第一次遇到在线文档出问题了。

之前用过语雀，界面确实漂亮，Markdown 支持也不错。但有几次都遇到保存失败，辛辛苦苦写了两小时的笔记，一个 Ctrl+W 手滑关掉，再打开就只剩下半小时前的版本。自动保存？有时候工作，有时候不工作，玄学。

后来试过 Notion，功能更强大，模板更丰富。但问题是...太慢了。不是说它本身慢，是网络问题导致的慢。你在国内用海外服务，打开一个页面要等三四秒，编辑的时候还会卡顿，这体验真的很折磨。挂梯子？公司不让啊。

还试过 Typora + 坚果云同步，这方案其实挺好的。本地 Markdown，云端备份，离线也能用。但问题是搜索不方便，文档一多就不好管理，而且移动端体验很差，手机上查个笔记跟翻垃圾堆似的。

作为一个前端开发，我对这些产品的痛点总结如下：

数据安全焦虑：你永远不知道哪天服务就挂了，或者突然要开始收费了（对，说的就是某度网盘）。数据在别人服务器上，心里总是不踏实。

网络依赖：地铁上想看笔记？抱歉，没网。公司内网不让连外网？抱歉，看不了。服务器在海外访问慢？抱歉，等着吧。

功能限制：想自定义样式？不行。想加个自己的脚本？不行。想导出成特定格式？对不起，会员功能。

导出困难：想把数据迁移走？给你导出一堆 HTML，图片全是外链，格式乱七八糟，你自己慢慢整理吧。

隐私问题：写的技术笔记算了，要是写点私密内容，放在别人服务器上总觉得不太放心。

但最让我下定决心自建的，还是那种"失控感"。你知道的，作为程序员，我们对"掌控"这事儿特别执着。代码要自己写，环境要自己配，工具要自己挑。把自己积累多年的知识体系托付给一个可能随时崩溃的第三方服务，这感觉就像把命根子交给别人保管。

而且说实话...咱们技术人多少有点"轮子情结"。

看到别人用现成的服务，心里就痒痒：这东西我也能做啊，而且还能做得更符合自己的需求。虽然自建要花时间，但想到能完全按照自己的想法来定制，那种成就感是用别人的产品永远体会不到的。

当然，理性地说，自建系统肯定有成本。时间成本、学习成本、维护成本。但对于我这样的前端开发者来说，这个过程本身就是学习。搭建的过程中会接触到 SSG（静态站点生成）、CI/CD、Markdown 渲染、搜索引擎集成等各种技术，这些知识在工作中也用得上。

而且，一次投入，长期受益。系统搭好之后，只需要偶尔更新个依赖，基本不用太多维护。数据都在 GitHub 上，写文档就是提交代码，天然带版本控制，还能随时回滚。

所以，就这么决定了：自己搞一套！

技术选型：在无数方案中纠结

决定自建之后，面临的第一个问题就是：用什么技术栈？

作为一个有选择困难症的程序员，我花了整整一周时间调研各种方案。这个过程...怎么说呢，就像逛淘宝买东西，每个都看起来挺好，但又都有点不完美。

WordPress？这可能是最成熟的方案了，插件生态丰富到爆炸，想要啥功能都有。但是...它是 PHP 的，我一个前端开发，每次改个样式都得去翻 PHP 代码？而且太重了，搭建一个知识库用不着那么复杂的 CMS 系统。Pass。

Hexo ？这个我很早就听说过，很多技术博客都是用它搭的。试了一下，确实挺简单的，hexo new post 写文章，hexo deploy 一键部署。但问题是...构建速度。文章一多，每次构建要等好几分钟，开发体验太差。而且它的主题配置都是基于 EJS 模板的，想改点东西得学习它那套模板语法，感觉又要投入学习成本。

Hugo ？听说构建速度超快，用 Go 写的，性能没的说。但我一看文档...全是 Go template 语法，什么 .Render、{{ range }}...对不起，告辞。我是前端开发，让我写 Vue/React 组件我在行，这种模板语法实在不想学。

VuePress 1.x？看到这个我眼睛一亮。用 Vue 写的，Markdown 里还能直接用 Vue 组件，这不就是为前端开发量身定制的吗？赶紧装一个试试。

结果...等构建的时候我去冲了杯咖啡，回来还在转圈圈。热更新也慢，改个配置要等半天才能看到效果。而且那个 1.x 版本已经不维护了，插件和主题都有点老旧。

VuePress 2.x？VuePress 都出 2.x 了，应该改进了吧？确实，底层换成了 Vite，理论上应该快很多。但是...生态还不完善，很多 1.x 的主题和插件都不兼容，文档也不够详细，感觉还处在快速迭代期，不太稳定。

Docusaurus？Facebook 出品的，专门为技术文档设计。试了一下，挺现代化的，支持 React，配置也清晰。但我总觉得...它更适合做产品文档，不太适合个人博客。而且它的默认主题比较硬核，都是那种文档网站的风格，不太符合我想要的"博客感"。

就在我快要选择困难症发作的时候，我看到了 VitePress。

打开官网一看，"Vite & Vue Powered Static Site Generator"。这不就是我想要的吗？基于 Vite，构建速度快；使用 Vue 3，可以写组件；专为文档设计，但不失灵活性。

赶紧 pnpm create vitepress 试一下。

pnpm create vitepress my-blog

几秒钟就装好了。pnpm run dev 启动开发服务器，瞬间就起来了。热更新？几乎感觉不到延迟。修改一个文件，浏览器立刻就更新了。

这速度...这就是我想要的体验啊！

但是光有框架还不够，我还需要一个好看的主题。VitePress 默认主题确实不错，但比较简洁，功能有限。我想要的是那种开箱即用的博客主题，最好有文章列表、标签分类、搜索功能等等。

然后我就发现了 @sugarat/theme（糖果主题）。

一看功能列表：

• 文章列表和分页 ✓
• 标签和分类 ✓
• 全文搜索（基于 Pagefind）✓
• 友链支持 ✓
• 评论系统 ✓
• RSS 订阅 ✓
• 暗黑模式 ✓

这不就是把我想要的功能都实现好了吗？果断选它！

最终技术栈就这么定了：

• VitePress 1.5+ - 快速、现代、灵活
• @sugarat/theme 0.4+ - 功能丰富的博客主题
• Vue 3 - 熟悉的框架，可以写自定义组件
• TypeScript - 类型安全，写配置文件更放心
• Pagefind - 静态全文搜索，免费且私有化
• GitHub Pages - 免费托管，自动部署
• pnpm - 快速、节省空间的包管理器

选型完了，开搞！

从零到一：搭建过程记录

项目初始化

周末早上，泡了杯咖啡，打开 VS Code，开始干活。

mkdir FrontendNotes
cd FrontendNotes
pnpm init

然后安装 VitePress 和糖果主题：

pnpm add -D vitepress @sugarat/theme vue

装完之后创建基础目录结构：

mkdir -p docs/.vitepress
mkdir -p docs/public/img

在 package.json 里加上脚本：

{
  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  }
}

创建 docs/.vitepress/config.mts，这是核心配置文件：

import { defineConfig } from "vitepress";
import { getThemeConfig } from "@sugarat/theme/node";

const blogTheme = getThemeConfig({
  author: "zhanglkx",
});

export default defineConfig({
  extends: blogTheme,
  lang: "zh-CN",
  title: "前端笔记",
  description: "前端技术博客",
  themeConfig: {
    nav: [
      { text: "首页", link: "/" },
    ],
  },
});

创建首页 docs/index.md：

---
layout: home

hero:
  name: "前端笔记"
  text: "Web 前端技术博客"
  tagline: 积跬步以至千里
---

然后激动地运行了一下：

pnpm run dev

"VitePress dev server running at http://localhost:5173"

打开浏览器，哇！一个简洁漂亮的首页就出来了。虽然还很简单，但这就是我自己的知识库雏形啊，那种成就感油然而生。

内容迁移的艰辛

有了框架，下一步就是把之前的笔记迁移过来。

我之前的笔记散落在各处：语雀上有一部分，本地 Markdown 文件有一部分，Notion 里也存了一些。这个整理过程...真的挺痛苦的。

从语雀导出是最麻烦的。语雀虽然支持导出 Markdown，但导出的格式需要大量清理：

• 图片全是外链，需要下载到本地
• 代码块的语言标识不标准
• 表格格式有时候会乱
• 数学公式需要重新调整

我写了个 Node.js 脚本来批量处理：

// 简化版的处理脚本
const fs = require('fs');
const path = require('path');

function processMarkdown(content) {
  // 处理图片链接
  content = content.replace(
    /!\[([^\]]*)\]\(https:\/\/cdn\.nlark\.com\/.*?\)/g,
    (match, alt) => `![${alt}](./images/${Date.now()}.png)`
  );

  // 修正代码块语言标识
  content = content.replace(/```js\n/g, '```javascript\n');

  return content;
}

// 批量处理目录下的文件
// ...省略具体实现

手动下载图片，批量重命名，更新引用路径...花了整整两天时间才把主要内容迁移完。

这个过程让我深刻体会到：数据导出困难真不是开玩笑的。在线服务为了留住用户，有意无意地增加了迁移成本。

核心配置：魔鬼在细节中

内容迁移完，我兴冲冲地开始配置网站。这时候问题来了。

rewrites：解决中文路径的困扰

我的文档目录结构是这样的：

docs/
├── 《JavaScript教程》笔记/
├── 《ES6 教程》笔记/
├── 《Vue》笔记/
└── ...

很自然对吧？中文目录名，清晰明了。但问题是，这些路径会直接映射到 URL：

https://xxx.github.io/《JavaScript教程》笔记/01.基础.html

在浏览器地址栏里会变成：

https://xxx.github.io/%E3%80%8AJavaScript%E6%95%99%E7%A8%8B%E3%80%8B%E7%AC%94%E8%AE%B0/01.%E5%9F%BA%E7%A1%80.html

这...也太丑了吧？而且分享链接的时候特别尴尬。

VitePress 的 rewrites 功能就是为了解决这个问题。它可以把文件路径映射到自定义的 URL：

export default defineConfig({
  rewrites: {
    "《JavaScript教程》笔记/:path*": "pages/js-tutorial/:path*",
    "《ES6 教程》笔记/:path*": "pages/es6-tutorial/:path*",
    "《Vue》笔记/01.基础/:path*": "pages/vue-basics/:path*",
  },
});

这样，URL 就变成了：

https://xxx.github.io/pages/js-tutorial/01.基础.html

清爽多了！

但这里有个坑：:path* 这个通配符很关键。我一开始以为只要配置目录映射就行了，结果发现子文件还是 404。后来才明白，:path* 表示匹配这个目录下的所有文件。

sidebar：侧边栏的艺术

有了 rewrites，侧边栏配置也要相应调整。sidebar 的 key 必须使用重写后的路径，不然匹配不上：

themeConfig: {
  sidebar: {
    "/pages/js-tutorial/": [
      {
        text: "JavaScript 教程",
        items: [
          { text: "基础", link: "/pages/js-tutorial/01.基础" },
          { text: "对象", link: "/pages/js-tutorial/02.内置对象" },
        ],
      },
    ],
  },
}

我当时配置完测试了一下，发现有些页面左侧边栏不显示。调试了半天才发现：sidebar 的 key 必须精确匹配当前页面的路径前缀。比如你在 /pages/js-tutorial/01.基础.html 这个页面，sidebar 的 key 就得是 /pages/js-tutorial/。

search：全文搜索的选择

对于知识库来说，搜索功能至关重要。糖果主题默认集成了 Pagefind，这是一个静态全文搜索工具。

为什么不用 Algolia？Algolia 确实强大，但需要注册账号，配置 crawler，还有月搜索量限制。对于个人博客来说，有点重了。

Pagefind 的好处是：

• 完全静态，构建时生成索引
• 没有外部依赖，速度快
• 支持中文分词
• 完全免费

配置超级简单，在 package.json 里加上 pagefind：

pnpm add -D pagefind

然后糖果主题会自动在构建时生成搜索索引。用户按 Cmd+K（Windows 是 Ctrl+K）就能唤起搜索框，体验跟 VS Code 一样丝滑。

主题定制：让它更像"我"

默认主题虽然好看，但我还是想加点个性化元素。

首页设计

我想要一个更有视觉冲击力的首页。修改 docs/index.md：

---
layout: home

hero:
  name: "前端笔记"
  text: "Web 前端技术博客"
  tagline: 积跬步以至千里，致敬每个爱学习的你
  image:
    src: https://raw.githubusercontent.com/Aniket965/Aniket965/master/pacman.svg
    alt: 前端笔记
  actions:
    - theme: brand
      text: 开始阅读
      link: /pages/javascript/
    - theme: alt
      text: GitHub
      link: https://github.com/zhanglkx

features:
  - icon: 💻
    title: 前端技术
    details: JavaScript、ES6、TypeScript、Vue、React 等
    link: /pages/javascript/
  - icon: 🎨
    title: 页面设计
    details: HTML5/CSS3、响应式设计
    link: /ui/html/
  - icon: 🛠️
    title: 技术文档
    details: 技术教程、总结、技巧
    link: /pages/tech-docs/
---

用了一个可爱的 Pacman SVG 作为 hero 图片，动态效果挺有趣的。

关于页面美化

关于页面是展示自己的地方，得好好设计一下。我用 Markdown + HTML + CSS 混合编写，加了渐变色标题、卡片布局、响应式设计：

<div style="text-align: center;">
  <h1 style="background: linear-gradient(120deg, #84fab0 0%, #8fd3f4 100%);
             -webkit-background-clip: text;
             -webkit-text-fill-color: transparent;">
    FrontendNotes
  </h1>
  <p style="font-size: 1.2rem; color: var(--vp-c-text-2);">
    现代化的前端知识管理平台
  </p>
</div>

用 CSS 变量 var(--vp-c-text-2) 可以自动适配明暗主题，这点很贴心。

踩坑实录：那些差点让我放弃的问题

如果说前面的搭建过程是在爬山，那接下来的踩坑经历就是在翻山越岭...而且是在雾霾天。

坑一：GitHub Actions 莫名其妙炸了

本地运行得好好的，pnpm run build 一点问题没有。满怀信心地推到 GitHub，配置好 GitHub Actions...然后就看到了一个大大的红叉。

点开日志一看：

ERR_PNPM_NO_LOCKFILE  Cannot install with "frozen-lockfile"
because pnpm-lock.yaml is absent

什么鬼？pnpm-lock.yaml 明明就在仓库里啊，我本地看得清清楚楚。

继续往上翻日志：

WARN  Ignoring not compatible lockfile at pnpm-lock.yaml

哦...原来是版本不兼容。我本地用的是 pnpm 9，但 GitHub Actions 的 workflow 里配置的是 pnpm 8。pnpm 8 读不了 9 的 lockfile 格式。

赶紧改 workflow 文件：

- name: Setup pnpm
  uses: pnpm/action-setup@v2
  with:
    version: 9  # 从 8 改成 9

推送，再次构建...成功了！

这个坑让我明白：CI 环境和本地环境保持一致有多重要。工具版本、Node 版本、依赖版本，任何一个不一致都可能导致问题。

坑二：网站样式全没了

GitHub Actions 构建成功了，满心欢喜地打开部署好的网站...

一片白茫茫。

不是 404，是页面打开了，但完全没有样式。右键查看源代码，HTML 结构是对的，但所有 CSS 和 JS 文件都 404。

打开浏览器开发者工具，Network 标签里一片红：

Failed to load resource: net::ERR_ABORTED 404 (Not Found)
/assets/style.xxx.css
/_assets/app.xxx.js

问题是：这些资源的路径前面都带了下划线 _。

Google 一番之后才知道：GitHub Pages 默认使用 Jekyll 处理静态文件。Jekyll 会忽略所有以 _ 开头的目录和文件。而 VitePress 构建出来的资源就在 _assets 目录下...

解决办法很简单：在构建产物根目录放一个 .nojekyll 文件，告诉 GitHub Pages 不要用 Jekyll 处理。

修改 workflow，在部署前加一步：

- name: Build
  run: pnpm run build

- name: Add .nojekyll file
  run: touch docs/.vitepress/dist/.nojekyll

- name: Deploy
  # ...

再次部署...这次样式出来了！网站活了！

坑三：base 路径的大小写陷阱

样式问题解决了，但又发现一个奇怪的问题：首页能打开，但点任何链接都是 404。

检查构建产物，文件都在。检查 Network 请求，路径也对...等等，路径真的对吗？

我的 GitHub 仓库名叫 FrontendNotes（驼峰命名），但配置文件里的 base 路径写的是：

base: "/frontend-notes/",  // 全小写

而 GitHub Pages 的 URL 是区分大小写的：

https://zhanglkx.github.io/FrontendNotes/  // 正确
https://zhanglkx.github.io/frontend-notes/ // 404

所有资源请求都用了小写路径，所以全部 404。

改成：

base: "/FrontendNotes/",  // 匹配仓库名

问题解决。

这个坑让我长记性了：GitHub Pages 的路径是区分大小写的，配置时一定要和仓库名保持一致。

坑四：侧边栏玩消失

网站上线后，我点开一篇 TypeScript 教程的文章，发现左侧边栏不见了。只有右侧的大纲（outline），左侧应该显示的文件目录消失了。

检查配置文件，sidebar 明明配置了啊：

sidebar: {
  "/《TypeScript 从零实现 axios》/": [
    // ...
  ],
}

后来才想起来：我配置了 rewrites！

rewrites: {
  "《TypeScript 从零实现 axios》/:path*": "pages/ts-axios/:path*",
}

用户访问的 URL 是 /pages/ts-axios/xxx，但 sidebar 的 key 是 /《TypeScript 从零实现 axios》/，当然匹配不上。

sidebar 的 key 必须使用重写后的路径：

sidebar: {
  "/pages/ts-axios/": [
    // ...
  ],
}

改完之后，侧边栏回来了。

坑五：子页面全是 404

网站基本能用了，但又发现一个问题：点击侧边栏的某些链接会 404。比如点击"初识 TypeScript"这个章节链接：

/pages/ts-axios/01.初识 TypeScript/

404。

但如果直接点击章节下的具体文章，比如"简介"，就能打开：

/pages/ts-axios/01.初识 TypeScript/01.简介

这个就能打开。

仔细一想就明白了：链接指向的是目录，VitePress 会尝试找这个目录下的 index.md 或 index.html。但我这些目录下没有 index 文件，所以 404。

解决办法有两个：

1. 修改链接，指向具体文件而不是目录
2. 为每个目录创建 index.md 导航页

我选择了第二种，因为这样用户体验更好。每个章节都有一个概览页面，列出该章节的所有文章，用户可以一目了然。

于是我花了一个下午，为所有需要的目录创建了 index.md：

---
title: 初识 TypeScript
---

# 初识 TypeScript

本章节将带你了解 TypeScript 的基础知识。

## 学习内容

- [简介](./01.简介) - 了解什么是 TypeScript
- [安装 TypeScript](./02.安装%20TypeScript) - 学习如何安装和配置
- [编写第一个程序](./03.编写第一个%20TypeScript%20程序) - 创建第一个 TS 程序

为了防止以后再遇到类似问题，我还写了个 shell 脚本来检查缺失的 index.md：

#!/bin/bash
echo "检查缺失的 index.md 文件..."

directories=(
    "docs/《TypeScript 从零实现 axios》/01.初识 TypeScript"
    # ... 更多目录
)

for dir in "${directories[@]}"; do
    if [ ! -f "$dir/index.md" ]; then
        echo "❌ 缺失: $dir/index.md"
    fi
done

以后每次添加新目录，运行这个脚本检查一下，就不会出问题了。

其他小坑

favicon 不显示：配置了 favicon 路径，但在 GitHub Pages 上不显示。原因是路径没有加上 base 前缀。解决办法是使用动态路径：

const ASSETS_PATH = process.env.GITHUB_ACTIONS ? "/FrontendNotes/" : "/";

head: [
  ["link", { rel: "icon", href: `${ASSETS_PATH}img/favicon.ico` }],
],

搜索功能不工作：按 Cmd+K 能打开搜索框，但搜不到任何内容。检查发现是 Pagefind 配置类型写错了。糖果主题的文档里有详细的配置说明，照着改就好了。

移动端样式错乱：某些自定义样式在手机上显示不正常。记得加上媒体查询和响应式布局。

这些坑踩完之后，网站终于稳定运行了。虽然过程艰辛，但每解决一个问题，成就感都会暴涨一点。

项目亮点：那些让我满意的地方

经过一番折腾，网站终于上线了。用了几个月下来，有几个特别让我满意的点。

性能：快到飞起

首屏加载速度：VitePress 生成的是纯静态 HTML，首屏加载不需要等 JavaScript 执行。在 3G 网络下，首页也能在 1 秒内完全渲染出来。

对比之前用在线文档，打开一个页面要等 3-4 秒，现在的体验简直是质的飞跃。

构建速度：本地开发时，热更新几乎是即时的。修改一个 Markdown 文件，按 Ctrl+S，不到 100ms 浏览器就更新了。这种流畅的体验让写文档变成了一种享受。

完整构建整个网站（200+ 篇文档），只需要 20 秒左右。对比之前用 Hexo，同样的文档量要构建 3-4 分钟。

搜索：强大且免费

Pagefind 的搜索体验出乎意料地好。

速度快：索引文件是预生成的，搜索时不需要网络请求，完全在本地完成。输入关键词，瞬间就能看到结果。

中文支持好：中文分词做得不错，搜"vue 生命周期"能匹配到相关文章，搜"生命周期"也能找到。

关键词高亮：搜索结果里会高亮显示匹配的关键词，还会显示上下文，一眼就能看到是不是自己要找的内容。

对比 Ctrl+F 浏览器原生搜索，这个体验好太多了。Ctrl+F 只能搜当前页面，而且没有分词，必须完全匹配才能找到。

响应式设计：多端友好

桌面端：1920px 宽屏下，内容居中显示，左右留白，阅读体验舒适。侧边栏、导航栏、目录大纲布局合理。

移动端：在手机上看文档也很方便。导航栏折叠成汉堡菜单，侧边栏可以滑出，字体大小合适，不需要缩放。

暗黑模式：晚上写代码的时候，切换到暗黑模式，眼睛舒服多了。而且暗黑模式下代码高亮配色也很漂亮。

自动化部署：Push 即上线

每次写完文档，只需要：

git add .
git commit -m "docs: 添加 React Hooks 笔记"
git push

剩下的交给 GitHub Actions。2-3 分钟后，网站就自动更新了。这种流畅的发布体验，是在线文档无法比拟的。

而且因为用了 Git 版本控制，所有修改都有记录。写错了可以回滚，想看某篇文章的历史版本，git log 一下就行。

扩展性：想加啥加啥

因为是自己搭建的系统，想加什么功能完全由我决定。

想加评论系统？集成 Giscus，基于 GitHub Discussions，10 分钟搞定。

想统计访问量？加上 Google Analytics 或者百度统计的代码就行。

想要 RSS 订阅？VitePress 可以在构建时生成 RSS feed。

想做 PWA 离线可用？装个 VitePress PWA 插件。

这种自由度，是用任何在线服务都做不到的。

使用三个月后的真实感受

现在这个系统已经用了三个月，说说真实的使用体验。

日常写作流程

早上到公司，打开 VS Code，切到博客项目。

git pull
pnpm run dev

开发服务器起来，浏览器自动打开 localhost:5173。

写文档就是写 Markdown：

## React Hooks 常见问题

### 为什么 useEffect 会执行两次？

在开发环境下，React 18 的 Strict Mode 会...

边写边预览，修改即时生效。写完了：

git add docs/《React》笔记/03.Hook/99.常见问题.md
git commit -m "docs: 添加 React Hooks 常见问题总结"
git push

等几分钟，文章就上线了。

整个流程非常自然，就像平时写代码一样。而且因为用 Git 管理，还能看到每篇文章的修改历史，这对技术博客来说很有价值。

对比在线文档

优势：

1. 速度：无论是打开网站，还是本地预览，还是搜索，都是秒级响应
2. 稳定：再也不用担心服务挂掉或者网络问题
3. 自由：想怎么定制就怎么定制，想加什么功能就加什么功能
4. 数据安全：所有数据都在 GitHub 上，还有完整的版本历史
5. 离线可用 ：git clone 下来，本地就能跑，不需要网络

劣势：

1. 有技术门槛：需要会用 Git，会写 Markdown，会配置 VitePress
2. 移动端编辑不便：手机上不太好编辑，必须用电脑
3. 协作不如在线工具：虽然可以通过 Git 协作，但不如在线文档方便

总体来说，对于我这样的前端开发者，优势远大于劣势。

数据积累

三个月下来：

• 文章数量：200+ 篇
• 文档总字数：约 50 万字
• GitHub 提交次数：300+ 次
• 每周访问量：稳定在 200+ 次（主要是自己访问 😂）

更重要的是，养成了记录的习惯。学到新东西就记下来，遇到问题就整理成笔记，时间久了就积累起来了。

开源分享：欢迎 Fork

既然花了这么多精力搭建，不如开源出来，说不定能帮助到其他人。

项目地址

GitHub 仓库 ：github.com/zhanglkx/Fr...

在线预览 ：zhanglkx.github.io/FrontendNot...

点个 Star 吧！⭐

仓库里有什么

FrontendNotes/
├── docs/                   # 所有文档内容
│   ├── .vitepress/        # VitePress 配置
│   │   └── config.mts     # 核心配置文件
│   ├── guide/             # 指南文档
│   │   ├── 项目搭建指南.md
│   │   └── 404问题排查指南.md
│   ├── 《JavaScript教程》笔记/
│   ├── 《ES6 教程》笔记/
│   ├── 《Vue》笔记/
│   ├── 《React》笔记/
│   └── ...
├── .github/
│   └── workflows/         # GitHub Actions 配置
│       └── deploy.yml     # 自动部署脚本
├── scripts/               # 辅助脚本
│   └── check-missing-index.sh
└── package.json           # 项目依赖

如何使用

如果你也想搭建类似的知识库，可以直接 Fork 这个项目：

1. Fork 仓库

点击右上角的 Fork 按钮，Fork 到你自己的账号下。

2. Clone 到本地

git clone https://github.com/你的用户名/FrontendNotes.git
cd FrontendNotes

3. 安装依赖

pnpm install

4. 本地开发

pnpm run dev

5. 修改配置

编辑 docs/.vitepress/config.mts，把里面的个人信息改成你自己的：

const DOMAIN_NAME = "你的用户名.github.io";
const BASE_PATH = "/你的仓库名/";

const blogTheme = getThemeConfig({
  author: "你的名字",
  // ...
});

6. 替换内容

删除 docs/ 下的文档，换成你自己的笔记。记得保留目录结构，或者根据需要调整 rewrites 配置。

7. 配置 GitHub Pages

在仓库设置中，找到 Pages 选项，Source 选择 "GitHub Actions"。

8. 推送代码

git add .
git commit -m "feat: 初始化我的知识库"
git push

等 GitHub Actions 完成部署，你的网站就上线了！

提供的文档支持

为了降低使用门槛，我写了两份详细的指南：

项目搭建指南：从零开始搭建，包括：

• 环境准备
• 技术选型分析
• 详细的搭建步骤
• 完整的配置说明
• 15 个常见问题的解决方案

404 问题排查指南：专门针对 404 问题，包括：

• 问题根本原因分析
• 5 步快速排查流程
• 预防措施和开发规范
• 常见问题 FAQ

遇到问题先查这两份文档，90% 的问题都能找到答案。

开源协议

项目使用 MIT License，这意味着：

• ✅ 可以随意使用、修改、分发
• ✅ 可以用于商业项目
• ✅ 可以二次开发
• ❌ 作者不承担任何责任（就是说出了问题别找我 😂）

唯一的要求是保留原作者的版权声明。

给想尝试的你

看到这里，你可能也有点心动，想搭建自己的知识库。那我给点建议。

你适合自建吗？

适合的人：

• 有一定前端基础，会 HTML/CSS/JS
• 会用 Git 和 GitHub
• 喜欢折腾，愿意花时间研究
• 希望完全掌控自己的数据
• 享受自己搭建系统的成就感

不太适合的人：

• 完全不懂技术，连 Git 都没听过
• 只想简单记笔记，不想学习新工具
• 时间很紧张，没有精力维护
• 追求开箱即用，不想碰配置

如果你属于后者，那老老实实用在线文档就好了，语雀、Notion、印象笔记都挺好。选择最适合自己的工具，才是最重要的。

给初学者的建议

从小处着手：不要一开始就想着做个大而全的知识库。先搭个最简单的版本，放几篇文档，能跑起来就行。然后慢慢迭代，一点一点加功能。

别怕踩坑：遇到问题是正常的，我也踩了无数个坑。但每个坑都是学习机会。Google、GitHub Issues、Stack Overflow，答案都能找到。

利用现有资源：直接 Fork 我的项目，在这个基础上改，会省很多时间。配置文件、工作流、文档结构都是现成的，改改就能用。

循序渐进：不要一次性想着加太多功能。评论、统计、RSS...这些都可以以后慢慢加。先把核心功能做好，写文档流程跑通，比什么都重要。

重视文档：自己写的配置，过几个月自己都忘了。所以一定要写注释，写文档。未来的自己会感谢现在的自己。

心理建设

会很耗时间：搭建、配置、踩坑、写文档...初期可能要投入几个周末的时间。要有这个心理准备。

不会一帆风顺：肯定会遇到各种问题。CI 构建失败、部署 404、样式不对...这都是家常便饭。但解决问题的过程，就是成长的过程。

长期价值：虽然初期投入大，但长期来看是值得的。系统一旦搭好，就能用很多年，还能不断迭代完善。

成就感满满：当你看着自己一手搭建的知识库上线，那种成就感是无可替代的。这是你的作品，是你的知识家园。

开源的意义：一点感悟

做完这个项目，我对开源有了更深的理解。

以前我只是开源项目的使用者。用 Vue、用 React、用各种开源工具。觉得这些都是理所当然的，免费用，挺好。

但当自己也开源一个项目之后，突然体会到了另一种快乐。

分享的快乐：把自己积累的知识和经验分享出来，如果能帮助到哪怕一个人，都会很开心。收到第一个 Star，第一个 Fork，那种感觉真的很奇妙。

社区的力量：开源项目不是一个人的事。有人提 Issue，有人提 PR，有人分享使用经验，这个项目就活了。它不再只是我的项目，而是大家共同的作品。

技术的传承：我搭建这个项目的时候，参考了无数前人的文章、代码、文档。现在我把自己的经验也写成文档，说不定也能帮到后来者。这就是技术社区的良性循环。

持续的动力：知道有人在用你的项目，会激励你持续完善它。加个新功能，修个 bug，写篇教程，都会更有动力。

最后

搭建这个知识库的经历，让我收获很多。不仅学到了 VitePress、GitHub Actions、CI/CD 这些技术，更重要的是找到了一种适合自己的知识管理方式。

现在回头看，当初那次在线文档崩溃，反而成了一个契机。如果没有那次经历，我可能还在用着不那么顺手的工具，一直将就着。

技术能让我们的生活更美好，前提是我们愿意花时间去探索、去实践。

如果你也有类似的困扰，也想搭建自己的知识库，不妨试试这个方案。也许一开始会有些困难，但走过这段路，你会发现一切都值得。

项目地址：github.com/zhanglkx/Fr...

如果对你有帮助，给个 Star 吧！有问题欢迎提 Issue，想贡献代码更欢迎发 PR。

一起来打造更好的知识管理工具，一起让技术社区变得更好。

---

2025 年 10 月，写于深夜

听着歌，敲着代码，记录这段搭建经历。窗外夜深人静，屏幕里代码跳动。这就是程序员的生活，也是程序员的快乐。

共勉。