读 VuePress（四）插件机制的设计

前言

从 9 月份开始，vuepress 源码进行了从新设计和拆分。先是开了个 next 分支，后来又合并到 master 分支，为即将发布的 1.x 版本作准备。

最主要的变化是：大部分的全局功能都被拆分红了插件的形式，以可插拔的方式来支撑 vuepress 的运做，这一点很像 webpack。

具体架构以下：

从图中咱们能够看出，vuepress 被划分红了两个部分：前端部分和服务端（Node.js）部分。

1. 前端部分

• 1.1 UI，也就是站点主题使用的代码。包括导航栏、侧边菜单、搜索框组件等。
• 1.2 当前 Vue 实例的扩展，提供了代码注入(inject)、实例混入(mixin)、组件拓展(components)、路由拓展(routes)方式。

2. 服务端部分

• 2.1 构建流程，这部分暴露出了 webpack、webpack-dev-server、markdown-it、动态模块的配置。
• 2.2 用户文件，包括配置文件和 markdown 文件（文档），这些文件至关于站点的元数据。
• 2.3 主题，这部分被划分为配置文件和布局组件。vuepress 提供了一份默认的主题。

在这个架构中，主题即插件。也就是说使用(开发)一个主题和使用(开发)一个插件的方式几乎一致。

• 2.4 插件 API，这是今天咱们重点介绍的部分，特别是插件机制的核心实现。

根据这个架构，vuepress 的插件即可以作不少事情了。具体用法能够参考文档。

内部插件和官方插件

让咱们先来了解一下 vuepress 的内部插件和官方插件都有些什么，借助插件机制作了哪些事情。

内部插件

1. 全局加强：默认用来实现全局应用加强的逻辑。 它使用 enhanceAppFiles 指定加强全局应用和主题的文件路径。凭着这个，vuepress 就能准确地找到你全局加强或是主题的文件所在地。

2. 布局组件：默认提供的布局组件。 它使用 clientDynamicModules 来实现动态引入布局相关的组件。

3. 页面组件：默认提供的页面组件（布局组件的子组件）。 它使用 clientDynamicModules 来实现动态引入页面相关的组件。

4. 根组件混入：默认往根组件混入的逻辑。 它使用 clientDynamicModules 来实现动态混入元信息。包括根组件的标题、语言等。

5. 路由：默认的生成路由逻辑。 它使用 clientDynamicModules 来实现动态注册路由。咱们的 markdown 文件在转换成 vue 组件后就是经过它自动注册到 vue-router 的。

6. 站点数据：默认的生成站点数据逻辑。 它使用 clientDynamicModules 来实现生成全局站点数据。咱们在页面里拿到的全局计算属性 $site 就是这样来的。

7. 模块化转化：将 cmd 代码转成 esm 代码的逻辑。 仍是用 clientDynamicModules 来实现将 cmd 代码转成 esm 代码。主要是由于 ClientComputedMixin 这个类先后端代码都要使用。

8. 样式加强 全局样式加强。使用 enhanceAppFiles 和 ready 钩子来实现（主题样式+用户样式+父主题样式）。

9. 样式覆盖 全局样式覆盖，使用 ready 钩子来实现，覆盖 config.styl 和父主题的 palette。

10. dataBlock数据注入 解析 blockType=data 的数据，使用 chainWebpack 和 enhanceAppFiles 来实现，对 blockType=data 类型的数据注入到 markdown 生成的 vue 组件里去，每一个组件能够访问本身的 $dataBlock 属性拿到。

官方插件

1. 活动的标题连接 它会在用户滚动页面时自动转变侧边栏的高亮标题。 它使用了 clientRootMixin 和 define 往根组件混入了滚动逻辑：监听 onScroll 事件，获取全部锚点元素并根据滚动距离计算出高亮的锚点。

2. 回到顶部 使用了 enhanceAppFiles 和 globalUIComponents 注册了一个全局组件：点击后能够滚动到页面顶部。

3. 博客

   • 3.1 使用 extendPageData 建立标签页和目录页
   • 3.2 使用 ready、clientDynamicModules、enhanceAppFile 建立页面元数据。

4. ga 谷歌分析站点的库。使用了 define 和 enhanceAppFiles 初始化了 ga。

5. 国际化（废弃） 可让你的站点拥有切换语言的能力。使用了 enhanceAppFiles 和 additionalPages 注册了个 I18n 布局组件。

6. 文档的最近更新时间 可让每一个文档页下面显示最近的 git 提交时间。使用 extendPageData 拓展了 $page 的 lastUpdated 属性。

7. 图片预览 集成了 medium-zoom。使用了 define、clientRootMixin 往根组件里混入了 zoom 的初始化和更新逻辑。

8. 分页 让共享侧边菜单栏的文档拥有分页切换的能力。使用了 enhanceAppFiles 定义了全部页面的索引和顺序。ready 定义了分页的规则如排序规则等、clientDynamicModules 生成动态模块给前端代码使用。

9. pwa 集成 service-worker 功能 - 9.1. 使用 ready 开启 serviceWorker 选项 - 9.2. 使用 alias 实现用 vue 当事件通道 - 9.3. 使用 define、globalUIComponents 注册更新 PWA 应用按钮组件 - 9.4. 使用 enhanceAppFiles 注入 register-service-worker 的初始化和更新逻辑 - 9.5. 使用 generated 经过 workbox-build 完成 sw 功能

10. 注册全局 Vue 组件 使用 enhanceAppFiles 把一个文件夹中的 vue 组件文件都注册好。

11. 搜索框 使用 alias 和 define 让搜索框能够动态引入。

12. 进度条 使用 clientRootMixin 和 enhanceAppFiles 集成 nprogress。

lerna

项目管理上，插件机制也使得原来的一个大项目拆成了 1 + N 的形式，package.json 也变得多了起来，为了管理这种项目，vuepress 引入了 lerna。

关于 lerna 的知识，有兴趣的读者能够参考：lerna管理前端packages的最佳实践。

核心实现

当一系列插件要使用时，须要经过 PluginAPI 和组成它的各类 Option 来实现。

总体流程大体以下：

这里我划分红了两个阶段，用虚线分隔，一个是调用前阶段，一个是调用后阶段。插件们被调用前，是会被载入以及注册的，以后化整为零，映射成若干个 Option 实例。

源码

1. PluginAPI 类，这部分代码包含了插件机制中的注册和调用实现。
   • 构造(constructor)：初始化选项、插件上下文、插件队列（可注册插件列表）、日志插件、初始化标志位、插件解析器属性，而后把选项们都装载进来（initializeOptions）。这里会把一个插件映射成若干个 Option 实例。 例如，一个插件只有 ready、chainWebpack、additionalPages 三个选项，则会获得三个 Option 实例。

     

   • 使用(use)，须要 _initialized 标志为 false 才能调用，用于确认哪些插件是能够被注册的：
     • 对于非对象类型的插件，会调用 normalizePlugin 方法将之转成对象

       

       • 期间会调用 _pluginResolver（ModuleResolver 实例) 来解析模块

         

         • 用于解析模块的 ModuleResolver 类，工做原理相似 webpack 的模块解析。源码
         • 这里值得一提的是 resolve 方法，它支持从非字符串包、npm 包、绝对路径、相对路径中解析模块。

           

         • 相对路径的模块先使用 node 的原生 path.resolve 方法解析获得绝对路径，而后交给解析绝对路径模块的方法处理。

           

         • 绝对路径、非字符串包和 npm 包会用通用模块 CommonModule 表示。

           

           

           

         • 通用模块有四个属性：entry、shortcut、name、fromDep。
       • 还会调用 flattenPlugin 拍平插件，主要是获取配置。
         • 若是传入配置是函数，则返回调用后的结果，入参为插件选项、插件上下文、PluginAPI 实例。

           

         • 传入的配置是对象，则返回一个拷贝后的对象。

           

     • 非 multiple 的插件，会根据插件名字去重。

       

     • 标准化后的插件，会加入到插件队列中去。
     • 最后，存在插件中使用插件的状况时，会调用 useByPluginsConfig 来实现。

       

       • 这里面的 normalizePluginsConfig 会将配置格式化成[[p1]、[p2]的形式]。
   • 初始化（initialize）：先将 _initialized 标志位置为 true，而后注册全部可用的插件。

     

     • 在初始化以前，内部插件的使用，会先于用户的插件。

       

     • 注册（applyPlugin）：到这里，插件已经被拆分红细化的选项，按照信息类（pluginName、shortcut）、钩子类（ready、compiled 等）、其余类（chainWebpack、chainMarkdown、enhanceAppFiles 等）按顺序链式注册（registerOption）。

       

       

       此时，一个 Option 实例中已经承载了若干个插件的逻辑了。
   • enabledPlugins 和 disabledPlugins 两个只读属性能够取启用（可注册）或禁用（不可注册）的插件列表。
   • getOption 能够取具体的一个选项实例，applyAsyncOption 和 applySyncOption 分别应用异步选项和同步选项中的逻辑（回调函数）。

选项和异步选项，插件的本体

2. Option 类 - 每一个实例初始化 key（选项标识） 和 items（这个选项所对应的函数们） 属性。

   • 重要方法：syncApply(也叫 apply)，对以前保存在实例中的 items 遍历调用 add 方法，若是 item 中的值是函数，则执行之取其返回值。

     

   • 在插件应用选项时若是匹配成功，会调用 add 方法将选项映射成 1-n 个对象推入 items 属性里。

     

   • 除了 add 还有 delete 和 clear 方法，不作赘述。（增删清）
   • 另外有 values、entries 和 appliedValues 三个只读属性，用于获取值、实体、已应用的值。
   • 管道方法(pipeline)，它将实例的 values 属性柯里化成一个组合函数，依次执行。

     

3. AsyncOption 类

   • asyncApply 异步版syncApply，调用函数的时候使用了 await。

     

   • parallelApply 若是说 pipeline 是串行，它就是并行：使用了 Promise.all

     

   • pipeline 同理，调用函数的时候使用了 await。

特殊选项

4. EnhanceAppFilesOption、ClientDynamicModulesOption、GlobalUIComponentsOption、DefineOption、AliasOption 类
   • AliasOption
     • 在建立 webpack 配置的时候调用
     • 重写 apply 方法：先调用 syncApply，而后将 appliedValues 取出，设置为 webpack 的 alias
   • ClientDynamicModulesOption
     • 在 prepare 阶段调用
     • 重写 apply 方法：从 appliedItems 取出应用的插件信息，遍历写入文件以待使用
   • DefineOption
     • 相似 AliasOption，只不过是设置 webpack 的全局变量
     • 最后在 injections 插件（DefinePlugin）触发时收集选项将 define 注入进去
   • EnhanceAppFilesOption
     • 在 prepare 阶段调用
     • 重写 apply 方法：从 appliedItems 取出插件信息，生成引入模块或者注册组件的代码文件
   • GlobalUIComponentsOption
     • 相似 ClientDynamicModulesOption，写全局 ui 组件文件

调用函数型 Option 时机

1. extendCli 建立 cli 命令时
2. chainMarkdown 和 extendMarkdown 建立 MarkdownIt 实例时
3. additionalPages 解析完全部页面后 三、extendPageData additionalPages 执行完以后，依赖 additionalPages 执行完的结果
4. ready 紧跟 additionalPages 以后
5. clientDynamicModules、enhanceAppFiles、globalUIComponents 紧跟 ready 以后
6. define、alias
   建立公共 webpack 配置后
7. chainWebpack
   建立 dev webpack 配置后、建立 build webpack 配置后
8. beforeDevServer
   webpack-dev-server 的 before 选项执行后
9. afterDevServer webpack-dev-server 的 after 选项执行后
10. generated build 完成后
11. updated 文件更新后
12. clientRootMixin
    clientDynamicModules 选项执行时

编写一个 vuepress 插件

我也写了一个小插件，它能够将你的 vuepress 站点下载成一个 pdf 文件：vuepress-plugin-export-site

源码

1. 使用 ready 选项
2. 借助 puppeteer 和 easy-pdf-merge 实现：从上下文中拿到路由信息，而后使用 puppeteer 遍历访问并下载，最后合并成一个大 PDF。
   • 由于须要下载 chromium，因此国内网络受限。咱们换成了 puppeteer-cn。
   • easy-pdf-merge 若是在 windows 下运行须要指定 jar 环境变量。

后记

咱们熟悉的 webpack、vue 也有插件系统，它们都有两个共同的特色：

1. 提供一个功能扩展点，让插件可以去扩展它。
2. 提供一个功能注册功能，让插件注册进来。

其实插件机制也能够看作设计模式的一种体现：抽离出变化的部分，保留不变的部分。这些变化的部分，即可以称之为插件。

在咱们造轮子的时候，若是轮子的功能愈来愈多，代码愈来愈臃肿的话，引入插件机制会让后续的开发更加灵活。

最后，帮插件机制的开发者真山同窗宣传一下，届时会有更加精彩的 vuepress 分享：