为什么我选择 Docusaurus 写技术博客

折腾技术博客这事我干过好几轮了。最早用 WordPress，后来用 Hexo，中间还试过自己拿 Go 写一个。每次都是写了几篇就荒废，原因不外乎：要么写起来麻烦，要么主题丑，要么改起来痛。

这次重新搭博客，我认真对比了当下三个主流的静态站点生成器（SSG）：Hugo、Astro、Docusaurus。结论是选了 Docusaurus。不是因为它最好，而是因为它最契合我「写技术博客」这个具体场景。

三个候选

Hugo

Go 写的，主打一个快。构建几千篇文章只要几百毫秒，单二进制部署，没有依赖地狱。

• 优点：构建飞快，单文件，主题生态成熟。
• 缺点：模板是 Go template，写复杂逻辑很拧巴；默认主题多偏「文档站」或老派博客；要做出自己想要的样子，改主题的成本不低。

Astro

新生代，主打 Islands Architecture，默认尽量少发 JS 到前端。可以混用 React / Vue / Svelte。

• 优点：现代、灵活，性能好，组件化，能做出很精致的页面。
• 缺点：对「纯文字博客」来说有点重；要配置的东西多；生态相对新，内容插件（比如 RSS、归档）要自己搭。

Docusaurus

React + MDX，Meta 出品。原本定位是文档站，但 blog 插件很完整。

• 优点：MDX 写作、代码块高亮开箱即用、RSS / 归档 / TOC 都现成、React 生态可复用、TypeScript 支持好。
• 缺点：构建产物带一定量 JS（比 Hugo 重）；定位偏文档，做博客要稍微「裁掉」一些默认元素。

我的取舍

我的需求很具体：

1. 以文章时间流为主，不要分类树、不要复杂的文档结构。
2. 写技术文章，代码块、TOC、MDX 组件是高频需求。
3. 能精细控制主题，想要一个克制的极简风，而不是套现成主题。
4. TypeScript + React，跟我日常技术栈一致，改起来顺手。

逐条对：

• 需求 1：三个都能做。Hugo 默认就是博客起家；Astro 和 Docusaurus 都能裁成纯时间流。
• 需求 2：Docusaurus 完胜。MDX + Prism 代码高亮 + 自动 TOC + 阅读体验，开箱即用。Hugo 要自己配高亮和 shortcodes，Astro 要自己接插件。
• 需求 3：三个都能改主题，但 Docusaurus 的 Infima 体系 + CSS 变量改起来很线性，覆盖一个 custom.css 就能大改。Hugo 主题是一大坨模板，魔改成本高。Astro 灵活但要自己搭整套布局。
• 需求 4：只有 Docusaurus 是 React / TS 原生。Hugo 是 Go template，Astro 虽支持 React 但本体是 .astro。

所以选 Docusaurus。代价是构建产物比 Hugo 重一点、带些 JS，但对我来说这点体积完全可接受——技术博客又不追求极致 LCP，可读性才是第一位。

实际怎么裁

Docusaurus 默认是个「文档站 + 博客」的形态，要做纯博客得裁掉一些东西：

• 关掉 docs 插件：preset-classic 里 docs: false，只留 blog。
• 博客当首页：blog 插件设 routeBasePath: '/'，主页直接是文章列表。
• 去掉标签：我个人不喜欢标签云，文章不写 tags，保持纯时间流。
• 保留归档和 RSS：这两个是博客的基本盘，Docusaurus blog 插件默认就给。
• 极简主题：覆盖 custom.css，黑白为主 + 单一强调色，正文限宽 680px，行高 1.7，参考 overreacted.io 那种阅读体验。

裁完之后，它就是一个干净的博客，没有文档站的 sidebar、没有 hero banner、没有多余卡片。

会再换吗

大概率不会。SSG 这东西，迁移成本主要在内容和主题。内容是 Markdown / MDX，可移植；主题是自己写的 CSS，也清楚。真要换，文章搬走不难。但 Docusaurus 目前满足我所有需求，没有换的理由。

选工具的真相是：没有最好的，只有最契合当前场景的。对我这个「会 React / TS、想精细控制样式、写技术文章为主」的人来说，Docusaurus 就是当前的最优解。