Zen Browser 插件开发指南：从入门到实践

2025-06-11 08:01:09作者：侯霆垣

前言

在 Zen Browser 生态系统中，插件机制是其核心功能之一。本文将深入探讨如何为 Zen Browser 开发自定义插件，涵盖从基础概念到高级实践的完整知识体系。

插件架构概述

Zen Browser 的插件系统采用管道式处理模型，内容在构建过程中会经过三个主要阶段：

转换器(Transformers)：对内容进行映射和修改
过滤器(Filters)：筛选需要保留的内容
发射器(Emitters)：生成最终输出文件

这种架构设计使得每个插件都能专注于单一职责，同时通过组合实现复杂功能。

开发环境准备

在开始插件开发前，需要确保：

熟悉 TypeScript 语言
了解 Markdown 和 HTML 的抽象语法树(AST)概念
安装必要的开发工具链

转换器插件开发

转换器是三种插件中最灵活也最复杂的一类，它能够在不同阶段对内容进行转换。

核心接口

interface QuartzTransformerPluginInstance {
  name: string
  textTransform?: (ctx: BuildCtx, src: string | Buffer) => string | Buffer
  markdownPlugins?: (ctx: BuildCtx) => PluggableList
  htmlPlugins?: (ctx: BuildCtx) => PluggableList
  externalResources?: (ctx: BuildCtx) => Partial<StaticResources>
}

开发实践

1. 文本预处理

textTransform 方法允许在 Markdown 解析前对原始文本进行操作：

textTransform(ctx, src) {
  // 将所有的TODO标记转换为大写
  return src.toString().replace(/TODO/g, "TODO")
}

2. Markdown AST 操作

通过 markdownPlugins 可以集成 remark 插件或自定义 AST 转换逻辑：

markdownPlugins() {
  return [
    () => (tree, file) => {
      visit(tree, "code", (node) => {
        // 为所有代码块添加行号
        node.data = node.data || {}
        node.data.lineNumbers = true
      })
    }
  ]
}

3. HTML AST 操作

htmlPlugins 允许使用 rehype 生态系统对生成的 HTML 进行操作：

htmlPlugins() {
  return [
    [rehypeHighlight, { ignoreMissing: true }] // 代码高亮
  ]
}

4. 添加自定义元数据

可以在转换过程中向文件添加自定义数据：

markdownPlugins() {
  return [
    () => (tree, file) => {
      const readingTime = calculateReadingTime(file.value)
      file.data.readingTime = readingTime
    }
  ]
}

过滤器插件开发

过滤器插件相对简单，主要用于内容筛选。

核心接口

interface QuartzFilterPluginInstance {
  name: string
  shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean
}

开发实践

1. 基础过滤器示例

export const OnlyPublished: QuartzFilterPlugin = () => ({
  name: "OnlyPublished",
  shouldPublish(_ctx, [_tree, vfile]) {
    return vfile.data?.frontmatter?.published !== false
  }
})

2. 复杂条件过滤

shouldPublish(ctx, content) {
  const [_, vfile] = content
  const isDraft = vfile.data?.frontmatter?.draft ?? false
  const isFuture = vfile.data?.frontmatter?.date 
    ? new Date(vfile.data.frontmatter.date) > new Date()
    : false
  return !isDraft && !isFuture
}

发射器插件开发

发射器负责将处理后的内容输出为最终文件。

核心接口

interface QuartzEmitterPluginInstance {
  name: string
  emit(ctx: BuildCtx, content: ProcessedContent[], resources: StaticResources): Promise<FilePath[]>
  getQuartzComponents(ctx: BuildCtx): QuartzComponent[]
}

开发实践

1. 基础发射器

export const JSONEmitter: QuartzEmitterPlugin = () => ({
  name: "JSONEmitter",
  async emit(ctx, content) {
    const fps: FilePath[] = []
    for (const [_, vfile] of content) {
      const fp = await emit({
        content: JSON.stringify(vfile.data),
        slug: vfile.data.slug!,
        ext: ".json",
      })
      fps.push(fp)
    }
    return fps
  },
  getQuartzComponents() {
    return []
  }
})

2. 页面渲染发射器

export const HTMLPageEmitter: QuartzEmitterPlugin = () => {
  const layout: FullPageLayout = {
    head: Head(),
    header: [Header()],
    pageBody: PageContent(),
    footer: Footer()
  }
  
  return {
    name: "HTMLPageEmitter",
    getQuartzComponents() {
      return Object.values(layout).flat()
    },
    async emit(ctx, content, resources) {
      const fps: FilePath[] = []
      for (const [tree, file] of content) {
        const html = renderPage({
          fileData: file.data,
          tree,
          ctx,
          resources
        })
        const fp = await emit({
          content: html,
          slug: file.data.slug!,
          ext: ".html",
        })
        fps.push(fp)
      }
      return fps
    }
  }
}