Skip to content

用 VitePress 搭一个博客:虚拟模块、RSS 和 cleanUrls ​

docs.emphant.com 用 VitePress 很自然:Markdown 即内容,侧边栏即导航。到了 blog.emphant.com,默认主题就不够用了——没有文章列表、没有日期、没有标签、没有 RSS。

可选方案有三个:

  1. 换 Hexo / Hugo / Astro;
  2. 用 VitePress 的博客插件;
  3. 在 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——它们都由构建过程从文件本身推导出来。

这就是选择「在静态生成器上扩一层」而不是「换一个博客框架」的理由:内容即数据,构建即集成。

记录方案,而不是记录结论。