插件一览

本模板的插件分为两类：一类由 默认主题内置（开箱即用、无需配置），一类由本模板 显式添加（在 .vuepress/configs/plugins.ts 中管理）。

由默认主题内置（无需重复添加）

插件作用
@vuepress/plugin-nprogress顶部加载进度条
@vuepress/plugin-back-to-top返回顶部按钮
@vuepress/plugin-active-header-links滚动时自动高亮当前标题
@vuepress/plugin-medium-zoom点击图片放大
@vuepress/plugin-git最后更新时间 / 贡献者（基于 Git）
@vuepress/plugin-copy-code代码块一键复制
@vuepress/plugin-markdown-hinttip / warning / danger / details 容器
@vuepress/plugin-markdown-tabcode-group 代码选项卡

这些插件由 @vuepress/theme-default 自动加载，重复添加反而会触发 plugin used multiple times 警告，因此不要在 plugins.ts 中再次引入。

由本模板显式添加

插件作用配置位置
@vuepress/plugin-shiki代码高亮（VS Code 同款引擎）plugins.ts
@vuepress/plugin-search内置全文搜索plugins.ts
@vuepress/plugin-container自定义容器 info / note / cautionplugins.ts
@vuepress/plugin-register-components全局组件自动注册plugins.ts
@vuepress/plugin-sitemap生成 sitemap.xml（仅生产环境）plugins.ts
@vuepress/plugin-pwa离线缓存 + 可安装（manifest + service worker，仅生产环境）plugins.ts
@vuepress/plugin-google-analyticsGA4 流量统计（配置 GA_ID 后启用）plugins.ts
@vuepress/plugin-docsearchAlgolia DocSearch 检索（配置 DOCSEARCH_* 后启用，替代内置 search）plugins.ts

PWA 说明

  • pwaPlugin 在生产构建时生成 manifest.webmanifest 与 service-worker.js，自动注入 <link rel="manifest">、主题色、苹果图标等标签，并支持「安装到桌面 / 主屏幕」与离线访问。
  • 当前 manifest 使用 public/favicon.svg 作为图标。如需更完整的安装体验，可在 public/icons/ 下补充 192×192 与 512×512 的 PNG 图标，并在 plugins.ts 的 manifest.icons 中追加条目。
  • 因 PWA 接管了资源缓存，主配置已设置 shouldPrefetch: false（否则会触发插件警告）。

Google Analytics 说明

  • googleAnalyticsPlugin 仅支持 GA4（测量 ID 形如 G-XXXXXXXXXX）。
  • 默认通过环境变量 GA_ID 注入，未配置时不注入任何脚本，保证模板开箱即可构建：
    # 方式一：构建时传环境变量
GA_ID=G-XXXXXXXXXX pnpm build

# 方式二：直接在 plugins.ts 的 SITE.gaId 中写死
  • 该插件仅在生产构建时生效（开发模式不发送统计）。

DocSearch 说明

  • docsearchPlugin 接入 Algolia DocSearch（基于 @docsearch/js v4，选项为 appId / apiKey / indexName）。
  • 需先到 docsearch.algolia.com 申请，拿到三项凭证后通过环境变量启用：
    DOCSEARCH_APP_ID=XXX DOCSEARCH_API_KEY=XXX DOCSEARCH_INDEX_NAME=XXX pnpm build
    也可在 plugins.ts 顶部的 DOCSEARCH 常量中直接写死。
  • 与内置 search 插件互斥：二者都会占用导航栏搜索框，故模板做了二选一——检测到 DocSearch 凭证时启用 DocSearch，否则回退到内置本地搜索。切勿同时启用两者，否则搜索框会异常。
  • 老项目从 appId/apiKey/indices 迁移注意：当前依赖为 DocSearch v4，使用 indexName（单数）。

新增文档

  • guide/markdown.md：Markdown 及本模板扩展语法的「写法速查表」（标题、列表、表格、代码组、各类容器、嵌入组件等）。
  • reference/plugin-authoring.md：如何编写 VuePress 插件（基本形态、常用钩子、四个示例、注册方式）。

可继续添加的插件（按需）

  • @vuepress/plugin-baidu-analytics：百度统计。
  • @vuepress/plugin-prismjs：若偏好 Prism 而非 Shiki（二选一即可）。

所有「显式添加」的插件都集中在 .vuepress/configs/plugins.ts，按需在数组内增删即可。

最后更新于:
文档贡献者: chenzw, WorkBuddy