跳到主要内容

个人博客网站搭建经验V2.0

一、架构演进：从 Astro 到 Docusaurus 2.2.0​

1.1 第一阶段回顾：Astro 架构的实践与局限​

在 V1.0 版本中，我们选择了 Astro 作为博客框架，主要基于以下考量：

  • 服务器优先渲染：默认输出纯 HTML，实现极致的首屏加载速度
  • 岛屿架构设计：按需加载交互组件，平衡性能与功能
  • 多框架兼容：支持混合使用 React、Vue 等组件生态

经过一段时间的实践，Astro 在个人博客场景中暴露出一些局限性：

  1. 文档系统支持不足：Astro 原生对多层级文档系统的支持较弱，需要大量自定义配置
  2. 社区生态相对年轻：相比成熟的文档框架，插件和主题资源有限
  3. 维护成本较高：随着内容增长，需要自行实现分类、标签、搜索等核心功能

1.2 切换动因：为何选择 Docusaurus 2.2.0？​

经过对多个文档框架的深入调研，最终决定迁移到 Docusaurus 2.2.0，主要基于以下核心考量：

1.2.1 原生文档系统支持​

Docusaurus 专为文档网站设计，提供开箱即用的文档功能：

  • 完整的文档结构：支持多层级目录、侧边栏导航、版本控制
  • 内置搜索功能：支持全文搜索，无需额外配置
  • Markdown 增强：支持 MDX、代码块、数学公式等高级特性

1.2.2 成熟的生态系统​

  • 丰富的插件生态：拥有完善的插件系统，可轻松扩展功能
  • 活跃的社区支持：由 Facebook 开源团队维护，更新稳定
  • 企业级应用验证：被 React、Jest、Redux 等知名项目采用

1.2.3 开发体验优化​

  • 热重载开发：修改内容实时预览，提升开发效率
  • TypeScript 支持：完整的类型支持，减少运行时错误
  • 配置驱动：通过配置文件即可完成大部分定制，降低维护成本

二、Docusaurus 2.2.0 框架深度解析​

2.1 核心架构设计​

Docusaurus 2.2.0 采用现代化的 React 技术栈，核心架构特点：

  • 基于 React 的静态站点生成器：使用 React 组件构建页面，支持服务端渲染
  • 插件化架构：所有功能通过插件实现，高度可扩展
  • 主题系统：支持自定义主题，可深度定制界面样式

2.2 关键技术特性​

2.2.1 文档系统核心功能​

// docusaurus.config.js 中的文档配置示例
docs: {
  routeBasePath: '/',           // 文档作为网站根路径
  sidebarPath: require.resolve('./sidebars.js'), // 侧边栏配置
  editUrl: 'https://github.com/...', // 在线编辑链接
  remarkPlugins: [require('remark-math')], // Markdown 插件
  rehypePlugins: [[require('rehype-katex'), options]], // 数学公式支持
}

2.2.2 多内容类型支持​

  • 文档 (Docs)：结构化知识库，支持版本控制
  • 博客 (Blog)：时间线式文章发布
  • 自定义页面 (Pages)：自由设计的独立页面
  • 插件页面 (Plugin Pages)：插件提供的功能页面

2.2.3 国际化与本地化​

  • 多语言支持：内置国际化系统，支持多语言文档
  • 本地化路由：自动生成语言前缀路由（如 /zh-cn/docs/）
  • 翻译管理：提供翻译工作流工具

2.3 性能优化机制​

Docusaurus 2.2.0 在性能方面做了大量优化：

  1. 代码分割：按路由自动分割代码，减少初始加载体积
  2. 预加载策略：智能预加载用户可能访问的页面
  3. 资源优化：自动压缩图片、CSS、JavaScript 资源
  4. PWA 支持：可配置为渐进式 Web 应用，支持离线访问

三、迁移实践：从 Astro 到 Docusaurus 的关键步骤​

3.1 内容迁移策略​

3.1.1 文档结构转换​

Astro 的内容结构：

src/content/posts/
  ├── post1.md
  └── post2.md

Docusaurus 的内容结构：

docs/
  ├── category1/
  │   ├── doc1.md
  │   └── doc2.md
  └── category2/
      └── doc3.md
blog/
  ├── 2023-01-01-post1.md
  └── 2023-01-02-post2.md

3.1.2 Front Matter 适配​

Astro 的 Front Matter：

---
title: 文章标题
date: 2023-01-01
tags: [标签1, 标签2]
---

Docusaurus 的 Front Matter：

---
title: 文章标题
date: 2023-01-01
tags: [标签1, 标签2]
slug: custom-url # 可选：自定义URL
---

3.2 配置迁移要点​

3.2.1 路由配置​

在 Docusaurus 中，路由配置更加直观：

// docusaurus.config.js
navbar: {
  items: [
    {to: '/docs/intro', label: '文档', position: 'left'},
    {to: '/blog', label: '博客', position: 'left'},
    {to: '/bookmarks', label: '书签', position: 'left'},
  ]
}

3.2.2 样式定制​

Docusaurus 使用 CSS Modules 和自定义 CSS：

/* src/css/custom.css */
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
}

3.3 插件生态系统集成​

Docusaurus 的强大之处在于其插件系统，本项目集成了以下关键插件：

  1. 本地搜索插件 (@easyops-cn/docusaurus-search-local)：

    • 支持中文全文搜索
    • 离线可用，无需外部服务
    • 可配置搜索范围（文档、博客、页面）

  2. 数学公式支持 (remark-math + rehype-katex)：

    • 支持 LaTeX 数学公式
    • 行内公式和块级公式
    • 自动加载 KaTeX CSS

  3. 自定义组件：

    • 首页特性展示组件
    • GitHub 贡献日历组件
    • 工具提示组件

四、Docusaurus 2.2.0 的进阶特性​

4.1 版本控制功能​

对于技术文档，版本控制至关重要：

// 多版本文档配置
versions: {
  current: {
    label: 'v2.0',
    path: 'v2.0',
  },
  '1.0': {
    label: 'v1.0',
    path: 'v1.0',
  }
}

4.2 主题定制能力​

Docusaurus 提供深度的主题定制：

  1. 组件替换 (Swizzling)：

    npm run swizzle @docusaurus/theme-classic Navbar

  2. 自定义布局：

    // src/theme/Layout.js
    export default function Layout(props) {
      return (
        <>
          <CustomHeader />
          <DefaultLayout {...props} />
          <CustomFooter />
        </>
      );
    }

4.3 部署优化​

4.3.1 静态资源优化​

Docusaurus 构建时自动优化：

  • 图片压缩和 WebP 转换
  • CSS 和 JavaScript 压缩
  • 资源哈希命名，支持长期缓存

4.3.2 CDN 集成​

// 配置 CDN 资源
stylesheets: [
  {
    href: 'https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css',
    type: 'text/css',
  }
]