#为什么不用现成的框架

搭博客这件事,最难的从来不是技术选型,而是「三年后你还敢不敢改它」。

我试过三种方案:Hexo 那类插件生态庞大的生成器、Next.js 那样的全栈框架、以及手写 HTML。第一种的问题是插件版本互相锁死,升级一次要花掉一个周末;第二种为了一个纯静态页面拖进几百兆的依赖和一套服务端运行时;第三种能在半小时内上线,但第二十篇文章之后,改导航栏就变成了体力活。

真正想要的东西其实很朴素:

  • 构建要快,快到改完字立刻能看到结果;
  • 产物要纯,dist/ 里只有 HTML、CSS、JS 和图片,扔到任何静态托管上都能跑;
  • 依赖要少,少到三年后 npm install 依然能装上;
  • 样式要自己写,不想为了改一个边距去翻框架的源码。

最后落到一个 300 行左右的构建脚本上。三个依赖,全部只在构建期出现:marked 负责 Markdown,highlight.js 负责代码高亮,gray-matter 负责解析 frontmatter。

#目录结构

CODE
.
├── content/
│   ├── posts/           # 每篇文章一个 .md
│   └── pages/about.md   # 独立页面
├── scripts/
│   ├── build.mjs        # 生成 dist/
│   └── dev.mjs          # 本地服务 + 监听重建
├── src/
│   ├── templates.mjs    # 所有页面的 HTML 模板
│   └── covers.mjs       # 自动生成文章封面
├── public/              # 原样拷贝到 dist 的静态资源
│   ├── assets/
│   ├── _headers
│   └── _redirects
├── site.config.json     # 站点名、导航、分页等
└── dist/                # 构建产物,不提交

这个结构最重要的一个决定是:public/ 与 src/ 分开。前者是「原样输出」,后者是「参与编译」。混在一起的项目,半年后你一定分不清哪个 HTML 是手写的、哪个是生成的。

#构建流程其实只有五步

JavaScript
// scripts/build.mjs(节选)
const posts = readPosts();          // 1. 读 md + 渲染 HTML
const allTags = collectTags(posts); // 2. 汇总标签
postEach(posts, writePostPage);     // 3. 逐篇出页面
writeIndex(posts, allTags);         // 4. 首页 / 归档 / 标签 / RSS
copyDir(PUBLIC, DIST);              // 5. 拷贝静态资源

每一篇文章在构建时会被算出一个对象:

JavaScript
{
  slug: 'zero-dependency-static-blog',
  title: '从零搭一个零依赖的静态博客',
  date: '2026-11-16',
  tags: [{ name: '工程实践', slug: '工程实践' }],
  html: '<h2 id="为什么不用现成的框架">…</h2>',
  headings: [{ depth: 2, id: '为什么不用现成的框架', text: '为什么不用现成的框架' }],
  minutes: 6
}

headings 是顺手摘出来的副产品——渲染标题时把纯文本和生成的 id 存进数组,右侧的目录、锚点跳转、滚动高亮就都有了,不需要额外解析一遍 HTML。

#Markdown 渲染里最容易出错的地方

marked 的默认输出足够好,但有三处必须自己接管。

第一,标题锚点。 中文标题直接做 id 会得到一堆 URL 编码后的乱码,我的做法是保留汉字、去掉标点:

JavaScript
function slugifyHeading(text, used) {
  let base = text
    .toLowerCase()
    .replace(/<[^>]+>/g, '')
    .replace(/[^\p{Script=Han}a-z0-9\s-]/gu, '')
    .trim()
    .replace(/\s+/g, '-');
  if (!base) base = 'section';
  let id = base, i = 2;
  while (used.has(id)) id = `${base}-${i++}`;  // 去重
  used.add(id);
  return id;
}

used 那个 Set 不能省。同一篇文章里出现两个「小结」是常态,重复的 id 会让目录跳到错误的位置。

第二,代码块要带语言标签和复制按钮。 这属于纯装饰,但对阅读体验影响很大:

JavaScript
code({ text, lang }) {
  const language = hljs.getLanguage(lang) ? lang : 'plaintext';
  const body = hljs.highlight(text, { language, ignoreIllegals: true }).value;
  return `<div class="code-block">
    <div class="code-head"><span class="code-lang">${label}</span>
      <button class="code-copy" data-copy>复制</button></div>
    <pre class="hljs"><code>${body}</code></pre>
  </div>`;
}

ignoreIllegals: true 是个保险。Highlight.js 遇到语法不完整的片段(比如你只贴了半段 JSX)会直接抛错,一旦抛错整个构建就挂了。

第三,表格要能横向滚动。 Markdown 表格在小屏上永远是溢出重灾区。我在 marked 输出后做了一次字符串替换,把每个 <table> 包进 overflow-x: auto 的容器里:

JavaScript
html = html
  .replace(/<table>/g, '<div class="table-wrap"><table>')
  .replace(/<\/table>/g, '</table></div>');

粗暴,但有效。比去写一个自定义 table renderer 省事得多。

#封面图:用 SVG 代替图片

每篇文章都需要一张封面,否则首页列表会参差不齐。找图太慢,AI 生图要么不稳定要么风格不统一,最后我让构建脚本直接生成 SVG:

JavaScript
const lines = wrapTitle(title);           // 按视觉宽度折行,中文记 1,英文记 0.56
const size = lines.length >= 3 ? 38 : 44; // 三行就缩字号

底色是六套预设的深色渐变,配上光晕和细网格,标题白字压在上面。每张 2 KB 左右,矢量、无版权问题、深浅色主题下都不违和。

这里有个细节值得说:折行不能按字符数算。「Cloudflare Pages 部署避坑清单」如果按每行 8 个字符切,会断成「Cloudflare Page / s 部署避坑清 / 单」这种灾难。按视觉宽度加权之后,虽然还是不能做到完美,但至少不会出现孤零零一个字母的尴尬。

#本地开发:不要引入第二个工具链

很多模板会给你一个 Vite 或者 Webpack 的 dev server。为了预览静态 HTML 而启动一个打包器,成本收益完全不成立。我用 Node 内置的 http 模块写了 60 行:

JavaScript
// scripts/dev.mjs(核心逻辑)
const server = http.createServer((req, res) => {
  const urlPath = decodeURIComponent(new URL(req.url, 'http://x').pathname);
  let file = path.join(DIST, urlPath);
  if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
  if (!fs.existsSync(file)) file = path.join(DIST, '404.html');  // 与线上行为一致
  const ext = path.extname(file);
  res.writeHead(fs.existsSync(file) ? 200 : 404, { 'Content-Type': MIME[ext] || 'text/plain' });
  fs.createReadStream(file).pipe(res);
});

再挂一个 fs.watch 监听 content/、src/、public/,文件变动就重建一次。改完保存,刷新浏览器,整个过程不到一秒。

#这套方案不适合谁

诚实地说,它有几处明确的短板:

场景 是否合适 原因
个人技术博客,几十到几百篇 合适 构建秒级,样式完全可控
需要评论、登录、后台 不合适 纯静态,没有服务端
多人协作写稿 勉强 没有草稿预览流程,只能靠 Git 分支
需要 i18n 多语言 不合适 模板里没有路由层

如果你的需求落在右边那几栏,老老实实用 Astro 或 Next.js。工具是拿来解决问题的,不是拿来证明审美的。

对我来说,这套东西最大的价值不是「零依赖」这个标签,而是每一行输出我都能解释清楚它为什么长这样。三年后回来改它,不需要先读一遍框架文档。