#为什么不用现成的框架
搭博客这件事,最难的从来不是技术选型,而是「三年后你还敢不敢改它」。
我试过三种方案:Hexo 那类插件生态庞大的生成器、Next.js 那样的全栈框架、以及手写 HTML。第一种的问题是插件版本互相锁死,升级一次要花掉一个周末;第二种为了一个纯静态页面拖进几百兆的依赖和一套服务端运行时;第三种能在半小时内上线,但第二十篇文章之后,改导航栏就变成了体力活。
真正想要的东西其实很朴素:
- 构建要快,快到改完字立刻能看到结果;
- 产物要纯,
dist/里只有 HTML、CSS、JS 和图片,扔到任何静态托管上都能跑; - 依赖要少,少到三年后
npm install依然能装上; - 样式要自己写,不想为了改一个边距去翻框架的源码。
最后落到一个 300 行左右的构建脚本上。三个依赖,全部只在构建期出现:marked 负责 Markdown,highlight.js 负责代码高亮,gray-matter 负责解析 frontmatter。
#目录结构
.
├── 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 是手写的、哪个是生成的。
#构建流程其实只有五步
// 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. 拷贝静态资源
每一篇文章在构建时会被算出一个对象:
{
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 编码后的乱码,我的做法是保留汉字、去掉标点:
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 会让目录跳到错误的位置。
第二,代码块要带语言标签和复制按钮。 这属于纯装饰,但对阅读体验影响很大:
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 的容器里:
html = html
.replace(/<table>/g, '<div class="table-wrap"><table>')
.replace(/<\/table>/g, '</table></div>');
粗暴,但有效。比去写一个自定义 table renderer 省事得多。
#封面图:用 SVG 代替图片
每篇文章都需要一张封面,否则首页列表会参差不齐。找图太慢,AI 生图要么不稳定要么风格不统一,最后我让构建脚本直接生成 SVG:
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 行:
// 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。工具是拿来解决问题的,不是拿来证明审美的。
对我来说,这套东西最大的价值不是「零依赖」这个标签,而是每一行输出我都能解释清楚它为什么长这样。三年后回来改它,不需要先读一遍框架文档。