主题
用 VitePress 搭一个博客:虚拟模块、RSS 和 cleanUrls
docs.emphant.com 用 VitePress 很自然:Markdown 即内容,侧边栏即导航。到了 blog.emphant.com,默认主题就不够用了——没有文章列表、没有日期、没有标签、没有 RSS。
可选方案有三个:
- 换 Hexo / Hugo / Astro;
- 用 VitePress 的博客插件;
- 在 VitePress 默认主题上自己扩一层。
选了第 3 个。理由很实际:同一套依赖、同一套构建、同一个部署流程。多引入一个框架,就多一套升级、多一份配置、多一个出问题的地方。
文章数据从哪来
VitePress 是静态生成器,Markdown 文件本身不暴露给 Vue 组件。最直接的办法是构建时扫描 posts/,把 frontmatter 整理成一个模块。
Vite 的虚拟模块正好适合:
ts
// .vitepress/posts.ts
export function postsPlugin(): Plugin {
const virtualId = 'virtual:posts'
const resolvedId = '\0' + virtualId
return {
name: 'emphant-posts',
resolveId(id) {
if (id === virtualId) return resolvedId
},
load(id) {
if (id !== resolvedId) return
const posts = readPosts()
return [
`export const posts = ${JSON.stringify(posts)}`,
`export const tags = ${JSON.stringify(collectTags(posts))}`,
'export default posts',
].join('\n')
},
}
}readPosts() 用 gray-matter 解析 frontmatter:
ts
const { data, content } = matter(fs.readFileSync(file, 'utf-8'))
return {
slug: name.replace(/\.md$/, ''),
url: `/posts/${slug}`,
title: data.title,
date: normalizeDate(data.date),
tags: data.tags ?? [],
description: data.description ?? '',
minutes: readingMinutes(content),
}排序按日期倒序,标了 draft: true 的直接过滤掉。这样草稿永远进不了列表、RSS 和 sitemap。
组件里直接 import:
js
import { posts, tags } from 'virtual:posts'构建时被打包成一份静态数组,运行时没有文件系统访问,也没有额外请求。
开发时怎么热更新
虚拟模块在 dev 下不会自己失效。新增一篇文章,列表不会自己刷新。需要监听目录:
ts
configureServer(server) {
const refresh = (file) => {
if (!file.startsWith(POSTS_DIR)) return
const mod = server.moduleGraph.getModuleById(resolvedId)
if (mod) server.moduleGraph.invalidateModule(mod)
server.ws.send({ type: 'full-reload' })
}
server.watcher.on('change', refresh)
server.watcher.on('add', refresh)
server.watcher.on('unlink', refresh)
}full-reload 比重建模块图简单可靠,写文章时整页刷新一下完全可以接受。
阅读时长
阅读时长不需要精确,但需要构建期算好,不能把全文塞进前端包让浏览器去数。
transformPageData 可以拿到源文件路径,直接读:
ts
transformPageData(pageData) {
if (!pageData.filePath) return
if (!pageData.relativePath.startsWith('posts/')) return
const src = fs.readFileSync(pageData.filePath, 'utf-8')
const { content } = matter(src)
pageData.frontmatter.minutes = readingMinutes(content)
}算法很粗:中文 500 字/分钟,英文 200 词/分钟,代码块和链接先剥掉。
ts
const cjk = (text.match(/[\u4e00-\u9fa5]/g) || []).length
const words = (text.match(/[A-Za-z0-9_]+/g) || []).length
return Math.max(1, Math.round(cjk / 500 + words / 200))准确率不重要,它的作用是给读者一个「这篇大概要读多久」的预期。
文章头信息
默认主题的文档页只有标题和正文。要在标题下面加日期、时长、标签,用 doc-before 插槽:
ts
Layout() {
return h(DefaultTheme.Layout, null, {
'doc-before': () => h(PostMeta),
})
}PostMeta.vue 读 useData().page.frontmatter,没有 date 就不渲染——所以这个插槽在归档页、标签页也不会错显示。
RSS
VitePress 没有内置 RSS。在 buildEnd 里直接写文件:
ts
buildEnd(siteConfig) {
const posts = readPosts()
const items = posts.map((p) => `
<item>
<title>${esc(p.title)}</title>
<link>https://blog.emphant.com${p.url}</link>
<pubDate>${new Date(p.date + 'T08:00:00+08:00').toUTCString()}</pubDate>
<description>${esc(p.description)}</description>
</item>`).join('')
fs.writeFileSync(
path.join(siteConfig.outDir, 'rss.xml'),
`<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"><channel>
<title>Emphant 技术随笔</title>
<link>https://blog.emphant.com</link>
${items}
</channel></rss>`,
)
}几个注意点:
pubDate必须是 RFC 822 格式(toUTCString()正好);- 正文里的
&、<必须转义,否则聚合器解析失败; - 描述不要塞全文 HTML,摘要就够,读者会点进来。
版本号带 buildEnd,所以每次构建都会重新生成,不会出现「加了文章但 RSS 没更新」。
cleanUrls 与 nginx
VitePress 开 cleanUrls: true 之后,链接是 /posts/why-multi-page,但构建产物仍然是 posts/why-multi-page.html。nginx 必须自己补扩展名:
nginx
location / {
try_files $uri $uri.html $uri/ =404;
}漏了 $uri.html,首页正常、所有文章页 404。这是上线时最容易漏的一行。
sitemap
VitePress 内置:
ts
sitemap: { hostname: 'https://blog.emphant.com' }构建时自动输出 sitemap.xml,包含所有页面。新增文章不需要手工维护。
这套方案不做什么
- 不做分页。文章量在几十篇以内,一页列表就够;真到几百篇再加。
- 不做评论。评论需要后端或第三方服务,与「静态、无账号」的原则冲突。
- 不做全文搜索索引服务。VitePress 的本地搜索(MiniSearch)在构建时生成索引,够用。
- 不做复杂的标签页。标签筛选在客户端完成,URL 用
?tag=记录,刷新后仍能还原。
结果
现在写一篇随笔的流程是:
bash
# 1. 新建 posts/xxx.md,写 frontmatter 和正文
# 2. 本地预览
npm run dev
# 3. 发布
./deploy.sh blog不需要改配置、不需要手动加索引、不需要更新 RSS——它们都由构建过程从文件本身推导出来。
这就是选择「在静态生成器上扩一层」而不是「换一个博客框架」的理由:内容即数据,构建即集成。