当前位置： 首页 > news >正文

VuePress 文档工作流：Vue 驱动的可交互技术文档平台

news 2026/6/22 5:41:55

1. VuePress 不是“另一个静态网站生成器”，而是 Vue 驱动的文档工作流中枢

你第一次在 GitHub 上看到一个开源项目的文档站点，页面清爽、左侧导航自动折叠、右侧代码块带复制按钮、搜索框秒出结果、主题切换丝滑、甚至还能嵌入实时运行的 Vue 组件——点开仓库一看，docs/.vuepress/config.js和满目录的.md文件静静躺在那里。这时候你大概率会想：“这又是个基于 Markdown 的静态站？用的是 Hexo？Docusaurus？还是 Jekyll？”
错。它极大概率是 VuePress。

VuePress 的核心身份，从来不是“静态网站生成器（SSG）”这个宽泛标签所能概括的。它本质是一个以 Vue.js 为底层渲染引擎、专为技术文档场景深度定制的开发体验平台。关键词不是“生成”，而是“驱动”；不是“静态”，而是“可交互”；不是“写文档”，而是“构建文档工作流”。它把 Vue 的响应式能力、组件系统、插件生态，全部下沉到文档创作的毛细血管里——你写的每一段 Markdown，背后都跑着真实的 Vue 实例；你配置的每一个themeConfig字段，都在调用 Vue 的 Options API；你插入的<Demo />组件，和你在业务项目里写的<Button />没有任何 runtime 差异。

这直接决定了它的适用边界：它不适合做企业官网首页（太重）、不适合做纯博客（RSS/分页支持弱）、更不适合做电商落地页（缺乏 CMS 集成）。但它对“需要频繁更新、强结构化、需嵌入交互示例、依赖团队协作”的技术文档场景，几乎是降维打击。比如 Vue 官方文档本身、Element Plus 文档、Vant 文档、甚至很多内部 SDK 的开发者手册，都选择 VuePress 而非更通用的 Docusaurus，原因就在这里——当文档开始需要“逻辑”而不仅是“内容”时，VuePress 的 Vue 基因就成了不可替代的生产力杠杆。

我去年接手一个物联网设备 SDK 的文档重构，旧版是用 MkDocs 生成的纯静态页。问题很快暴露：API 参数表格需要手动维护，新增一个字段就得改三处（参数名、类型、描述）；组件示例只能贴截图，用户无法一键复制代码；不同设备型号的差异配置，靠人工在 Markdown 里加<!-- if device-A -->注释，CI 构建时再用脚本替换，错误率高达 37%。换成 VuePress 后，我们把参数定义抽成 JSON Schema，用 Vue 组件动态渲染表格；所有示例代码块封装成<CodeBlock lang="ts" :code="apiExample" />，点击复制触发navigator.clipboard.writeText()；设备型号差异通过process.env.VUEPRESS_DEVICE_TYPE环境变量 +<ClientOnly>组件按需加载。上线后文档更新耗时从平均 2 小时/次降到 15 分钟/次，PR 合并前的文档校验失败率归零。这不是工具升级，是工作流范式的迁移。

提示：别被“Press”二字误导。VuePress 和 WordPress 没有任何关系，它不提供后台管理界面，也不存储用户数据。所有“动态”能力都发生在构建时（build time）或客户端（client side），最终产物仍是纯静态 HTML/CSS/JS 文件，可直接部署到任何 CDN 或对象存储。

2. 为什么是 config.js 而不是 vue.config.js？解构 VuePress 的双层架构设计

当你执行vuepress dev docs启动本地服务，控制台输出的路径通常是http://localhost:8080/，但你打开浏览器开发者工具，Network 面板里却看不到任何/api/请求，所有资源都是.html、.js、.css。这说明 VuePress 的“服务端”只存在于构建阶段，运行时完全无服务端依赖。而这一切的调度中枢，就是docs/.vuepress/config.js—— 它不是 Vue CLI 的vue.config.js，也不是 Vite 的vite.config.js，而是一个专为文档场景抽象的配置契约。

这个文件的存在，揭示了 VuePress 的核心架构：双层编译模型。第一层是 VuePress 自身的构建系统（基于 Webpack 4，VuePress 2 已切至 Vite），负责解析config.js、加载主题、处理 Markdown 渲染管道；第二层是 Vue 应用本身的编译，由 VuePress 注入的@vue/compiler-sfc处理.vue单文件组件。config.js就是这两层之间的唯一胶水。

我们来拆解一个典型config.js的关键字段及其真实作用：

// docs/.vuepress/config.js module.exports = { title: 'My SDK Docs', // 仅用于生成 <title> 标签，不影响路由 description: 'A lightweight IoT SDK', // 用于生成 <meta name="description">，SEO 基础 base: '/sdk/', // 关键！所有静态资源路径的公共前缀，必须以 / 开头且结尾带 / head: [ ['link', { rel: 'icon', href: '/favicon.ico' }], // 注入 HTML <head> 的原始标签 ['script', {}, 'window.$crisp=[];'] // 可直接写 JS 字符串，无需转义 ], themeConfig: { logo: '/logo.png', // 主题级 Logo，由主题决定渲染位置（通常左上角） nav: [ // 导航栏菜单，数组顺序即显示顺序 { text: '指南', link: '/guide/' }, { text: 'API', link: '/api/' }, { text: 'GitHub', link: 'https://github.com/xxx' } ], sidebar: { // 侧边栏配置，支持对象或函数 '/guide/': [ { title: '快速开始', collapsable: false, // 是否可折叠，默认 true children: ['/guide/install.md', '/guide/quickstart.md'] } ] } }, plugins: [ '@vuepress/plugin-back-to-top', // 官方插件，无需额外安装 ['@vuepress/plugin-medium-zoom', { selector: 'img' }], // 插件选项传参 require('./plugins/custom-plugin') // 自定义插件，路径需 resolve ] }

这里最易被误解的是base字段。很多人以为它只是 URL 前缀，实则它直接影响整个构建产物的物理结构。假设base: '/sdk/'，那么构建后dist/目录下会生成dist/sdk/index.html、dist/sdk/guide/install.html。如果你部署到 GitHub Pages 的username.github.io/repo仓库，base必须设为/repo/，否则所有资源请求都会 404。我见过太多团队因为忽略这点，在 CI 部署后发现样式全丢、导航失效，排查三天才发现base写成了/。

另一个关键点是themeConfig.sidebar的函数用法。当你的文档超过 200 个页面，手动维护children数组会崩溃。这时可以这样写：

sidebar: () => { const sidebar = {} // 自动扫描 /guide/ 下所有 .md 文件，按文件名排序生成侧边栏 const guideFiles = require('fs').readdirSync('docs/guide') .filter(f => f.endsWith('.md')) .sort() sidebar['/guide/'] = [ { title: '指南', children: guideFiles.map(f => `/guide/${f}`) } ] return sidebar }

这本质上是在构建时执行 Node.js 代码，动态生成配置。VuePress 的设计哲学在此体现：配置即代码（Configuration as Code），而非 YAML 或 JSON 的静态声明。它允许你用 JavaScript 的全部能力去解决文档组织的复杂性，这是 Docusaurus 的docusaurus.config.js（基于 JS 对象）或 MkDocs 的mkdocs.yml（纯 YAML）无法做到的。

注意：config.js中不能使用import语法（Node.js 默认不支持 ES Module），必须用require()。若需使用 ES Module，需将文件改为config.ts并配置 TypeScript 支持，但这会增加构建复杂度，非必要不推荐。

3. Markdown 不再是“标记语言”，而是 Vue 组件的语法糖

在 VuePress 里，.md文件的解析过程远比你想象的复杂。它不是简单地把# 标题转成<h1>标题</h1>，而是经历了一条完整的 Vue 编译流水线：Markdown → AST → Vue SFC → Render Function → VNode → DOM。这意味着你写的每一行 Markdown，最终都运行在 Vue 的响应式系统之上。

我们以一个最简单的例子切入：

<!-- docs/guide/install.md --> # 安装 请根据你的包管理器选择命令： - npm: `npm install my-sdk` - yarn: `yarn add my-sdk` - pnpm: `pnpm add my-sdk`

这段代码在 VuePress 中会被解析为：

  1. Markdown 解析器（marked）将其转为 AST（抽象语法树），识别出heading、paragraph、list、code等节点；
  2. VuePress 的 Markdown Loader将 AST 节点映射为 Vue 组件标签，例如<h1>→<Heading level="1">，<code>→<Code>；
  3. Vue 编译器将这些自定义标签编译为 Render Function，其中<Code>组件会接收textprop 并渲染高亮代码；
  4. 最终在浏览器中，<Code>组件的mounted钩子触发 Prism.js 语法高亮。

所以，当你在 Markdown 里写：

<CodeGroup> <CodeGroupItem title="npm"> ```bash npm install my-sdk
```bash yarn add my-sdk ``` ```

这根本不是什么“扩展语法”，而是标准的 Vue 组件嵌套。<CodeGroup>是一个注册在全局的 Vue 组件（通常由主题或插件提供），<CodeGroupItem>是它的子组件，title是 props，<pre><code>是默认插槽内容。你可以像在.vue文件里一样，给它加v-if、v-for、:class，甚至@click事件。

我曾为一个支持多语言的 SDK 文档实现“代码块语言自动切换”。需求是：用户在页面顶部选择 “JavaScript” 或 “TypeScript”，所有代码块应实时切换为对应语言的示例。传统方案需为每种语言维护独立 Markdown 文件，维护成本爆炸。而 VuePress 方案只需：

<!-- docs/api/client.md --> <ClientOnly> <template #default> <div> <select v-model="$page.lang"> <option value="js">JavaScript</option> <option value="ts">TypeScript</option> </select> <CodeBlock :lang="$page.lang" :code="getExample($page.lang)" /> </div> </template> </ClientOnly>

配合enhanceApp.js注入$page.lang响应式数据，getExample()方法根据语言返回预定义的代码字符串。整个过程无需刷新页面，代码块实时更新。这种能力，是任何纯静态 SSG 望尘莫及的。

更进一步，VuePress 允许你用<script>和<style>标签直接在 Markdown 里写逻辑和样式：

# 动态计数器 当前点击次数：<span>{{ count }}</span> <button @click="count++">点我</button> <script> export default { data() { return { count: 0 } } } </script> <style scoped> button { background: #42b883; color: white; border: none; padding: 8px 16px; border-radius: 4px; } </style>

这已经完全突破了“文档”的范畴，进入了“微型应用”的领域。VuePress 的强大，正在于它模糊了文档与应用的边界——当你需要文档具备应用级交互时，它就在那里，无需切换技术栈。

提示：<script>和<style>在 Markdown 中的使用有严格限制。<script>必须是export default导出的对象，不能是 IIFE；<style>默认是scoped，如需全局样式需显式写scoped="false"。这些限制是为了保证构建时的可预测性，避免意外污染全局环境。

4. 主题不是“皮肤”，而是可编程的文档 UI 框架

VuePress 的主题机制，是它区别于其他 SSG 的最大护城河。很多人以为换主题就像换 WordPress 主题一样，下载 zip 包解压覆盖即可。实际上，VuePress 主题是一个完整的 Vue 应用框架，它定义了文档站点的骨架、布局、导航逻辑、搜索算法、甚至构建时的预处理规则。

官方主题@vuepress/theme-default是学习主题开发的最佳起点。它的目录结构清晰展示了主题的模块化设计：

node_modules/@vuepress/theme-default/ ├── layouts/ # 页面布局组件（Layout.vue 是所有页面的父容器） ├── components/ # 可复用 UI 组件（Badge.vue, BadgeGroup.vue） ├── styles/ # 样式文件（index.styl, palette.styl） ├── templates/ # HTML 模板（index.html, 404.html） ├── enhanceApp.js # 应用增强钩子（注入全局属性、组件、指令） ├── index.js # 主题入口，导出主题配置和生命周期钩子 └── ...

当你在config.js中写theme: '@vuepress/theme-default'，VuePress 会：

  1. 加载index.js，执行其导出的extendPageData钩子，为每个页面注入frontmatter数据；
  2. 使用layouts/Layout.vue作为根布局，将 Markdown 渲染内容注入<Content />插槽；
  3. 在enhanceApp.js中注册全局组件（如<Badge>）、指令（如v-pre）、混入（mixin）；
  4. 编译styles/下的 Stylus 文件，生成 CSS。

这意味着，你可以像开发 Vue 应用一样定制主题。比如，你想在每个页面右上角添加一个“编辑此页”按钮，链接到 GitHub 对应的 Markdown 文件：

// .vuepress/enhanceApp.js export default ({ app, router, siteData }) => { // 注入全局方法 app.config.globalProperties.$getEditLink = (path) => { return `https://github.com/your-org/your-repo/edit/main/docs${path}` } }

然后在自定义布局中：

<!-- .vuepress/layouts/Layout.vue --> <template> <div class="theme-container"> <Navbar /> <Sidebar /> <main class="main"> <Content /> <a v-if="$page.relativePath" :href="$getEditLink($page.relativePath)" class="edit-link" > ✏️ 编辑此页 </a> </main> </div> </template>

这比在 Docusaurus 中修改docusaurus.config.js的customFields或在 MkDocs 中写 Python 插件要直观得多——你操作的是熟悉的 Vue 模板和 JavaScript，而不是配置项或钩子函数。

更强大的是主题继承。VuePress 2 引入了主题继承机制，允许你创建一个“子主题”复用父主题的所有功能，只覆盖需要修改的部分：

// .vuepress/theme/index.js const { path } = require('@vuepress/utils') const defaultTheme = require('@vuepress/theme-default') module.exports = (options, ctx) => { return { ...defaultTheme(options, ctx), layouts: { Layout: path.resolve(__dirname, 'layouts/Layout.vue') // 覆盖 Layout }, alias: { '@theme/components/Badge.vue': path.resolve(__dirname, 'components/CustomBadge.vue') // 覆盖组件 } } }

我曾为一个金融类 SDK 设计深色模式主题。没有从零造轮子，而是继承@vuepress/theme-default，只重写了styles/palette.styl中的色值变量，并在enhanceApp.js中监听系统偏好：

// .vuepress/enhanceApp.js export default ({ app }) => { const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches app.config.globalProperties.$isDarkMode = prefersDark document.documentElement.classList.toggle('dark-mode', prefersDark) }

然后在styles/index.styl中：

if $isDarkMode $textColor = #e6e6e6 $borderColor = #444 else $textColor = #333 $borderColor = #eee

整个过程不到 200 行代码，却实现了专业级的深色模式，且完全兼容官方主题的所有功能。这就是 VuePress 主题机制的威力：它不强迫你接受一套封闭的 UI 规范，而是给你一个可编程的 UI 框架，让你用 Vue 的方式去塑造文档的形态。

注意：自定义主题时，务必在package.json的dependencies中声明对@vuepress/core和@vuepress/theme-default的依赖，否则在 CI 环境中可能因 peer dependency 解析失败导致构建中断。

5. 插件不是“功能补丁”，而是构建流水线的可编程节点

VuePress 的插件系统，是其工程化能力的集中体现。它不像 VS Code 插件那样运行在编辑器进程里，而是深度嵌入到 VuePress 的构建生命周期中，成为一条可编程的流水线。每个插件都可以在特定的构建阶段（如ready、generated、afterBuild）注入逻辑，操作页面数据、修改 HTML、生成额外文件，甚至启动 HTTP 服务。

我们以官方插件@vuepress/plugin-search为例，看它如何工作：

// node_modules/@vuepress/plugin-search/index.js module.exports = (options = {}) => ({ name: 'vuepress-plugin-search', // 在 VuePress 准备就绪后执行 ready() { // 读取所有页面的 $page.title 和 $page.excerpt const pages = this.app.pages const searchIndex = pages.map(page => ({ title: page.title, path: page.path, excerpt: page.excerpt })) // 将索引序列化为 JSON，写入 dist/search.json fs.writeFileSync( path.join(this.app.dir.dest, 'search.json'), JSON.stringify(searchIndex) ) }, // 在客户端应用增强时注入搜索组件 enhanceApp({ app }) { app.component('SearchBox', SearchBox) } })

这个插件做了两件事：构建时生成搜索索引文件，客户端时注册SearchBox组件。它没有修改任何现有代码，却完整实现了全文搜索功能。这就是 VuePress 插件的设计哲学：职责单一、阶段明确、副作用可控。

实际项目中，我遇到过一个硬需求：SDK 文档需要支持“版本切换”，用户选择 v1.2.0 后，所有 API 链接自动跳转到该版本的文档，且搜索结果只包含 v1.2.0 的页面。这需要：

  1. 构建时为每个版本生成独立的dist/v1.2.0/目录；
  2. 在页面中注入版本选择器组件；
  3. 所有内部链接自动添加版本前缀；
  4. 搜索索引按版本隔离。

用传统 SSG 需要写复杂的构建脚本。而 VuePress 插件方案如下：

// .vuepress/plugins/version-switcher.js module.exports = (options) => { const versions = options.versions || ['v1.0.0', 'v1.1.0', 'v1.2.0'] return { name: 'version-switcher', // 在页面数据生成后，修改所有页面的 $page.path extendPageData($page) { const version = process.env.VERSION || 'latest' if (version !== 'latest') { $page.path = `/${version}${$page.path}` } }, // 在构建完成后，为每个版本生成独立的 dist 目录 async afterBuild(app) { for (const version of versions) { process.env.VERSION = version await app.build() // 将 dist/ 重命名为 dist/v1.2.0/ fs.renameSync('dist', `dist/${version}`) } } } }

配合config.js中的base: '/v1.2.0/'，整个版本切换系统就完成了。插件没有侵入核心逻辑，却通过钩子函数精准控制了构建流程的每个环节。

另一个高频需求是“自动提取 API 文档”。很多团队用 TypeScript 写 SDK，希望从src/index.ts的 JSDoc 注释自动生成 API 页面。这需要：

  1. 构建时解析 TypeScript 源码；
  2. 提取@param、@returns、@example等 JSDoc 标签；
  3. 生成对应的 Markdown 文件。

我们用typedoc和vuepress-plugin-typedoc插件组合实现：

# 安装依赖 npm install typedoc @vuepress/plugin-typedoc --save-dev
// .vuepress/config.js module.exports = { plugins: [ ['@vuepress/plugin-typedoc', { entryPoints: ['../src/index.ts'], tsconfig: '../tsconfig.json', out: 'api', // 生成的 Markdown 存放在 docs/api/ 目录 excludePrivate: true, readme: 'none' }] ] }

执行vuepress build docs时，插件会调用typedoc解析源码，生成docs/api/Client.md、docs/api/Options.md等文件，内容包含完整的参数表格、返回值类型、示例代码。整个过程全自动，且与文档其他部分无缝集成——你可以在guide/quickstart.md中直接[](/api/Client.md)链接到自动生成的 API 页面。

提示：插件开发时，务必使用this.app.options访问用户配置，用this.app.siteData获取站点元数据，用this.app.pages操作页面集合。避免直接操作fs或path模块，应使用@vuepress/utils提供的fs,path工具函数，确保跨平台兼容性。

6. 从零搭建一个生产级 VuePress 文档站：我的标准化工作流

现在，让我们把前面所有概念串联起来，走一遍一个真实生产环境的 VuePress 文档站搭建全流程。这不是“Hello World”教程，而是我在三个不同规模项目中验证过的标准化工作流，包含所有避坑细节。

6.1 初始化与目录规划：拒绝“docs/ 一把梭”

很多团队第一步就错了：直接在项目根目录下建docs/，把所有东西塞进去。这会导致后续 CI/CD、多版本发布、主题开发全部混乱。正确的目录结构应该是：

my-sdk/ ├── src/ # SDK 源码 ├── packages/ # 如果是 monorepo ├── docs/ # 文档源码（仅 Markdown 和配置） │ ├── .vuepress/ # VuePress 专属配置 │ │ ├── config.js │ │ ├── enhanceApp.js │ │ ├── layouts/ │ │ └── plugins/ │ ├── guide/ # 指南类文档 │ ├── api/ # API 文档（可由 typedoc 自动生成） │ └── public/ # 静态资源（favicon.ico, logo.png） ├── package.json └── README.md

关键点：

  • docs/是独立的文档工作区，与src/物理隔离；
  • docs/.vuepress/下不放任何业务代码，只放 VuePress 相关配置；
  • docs/public/用于存放favicon.ico、logo.png等静态资源，它们会原样复制到dist/根目录；
  • api/目录不手动编写，由插件自动生成，避免重复劳动。

初始化命令：

# 进入 docs 目录 cd docs # 初始化 package.json（注意：这是 docs/ 的 package.json，不是项目根目录的） npm init -y # 安装 VuePress（VuePress 2 推荐） npm install -D vuepress@next @vuepress/plugin-back-to-top @vuepress/plugin-medium-zoom # 创建基础配置 mkdir .vuepress echo "module.exports = { title: 'My SDK Docs' }" > .vuepress/config.js

6.2 配置 CI/CD：GitHub Actions 自动部署到 GitHub Pages

生产环境必须自动化。以下是一个经过实战检验的.github/workflows/deploy.yml：

name: Deploy Docs on: push: branches: [main] # 监听 main 分支推送 paths: - 'docs/**' # 仅当 docs/ 目录变更时触发 - '.github/workflows/deploy.yml' jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 # 必须！否则 git push 会失败 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies run: cd docs && npm ci - name: Build docs run: cd docs && npm run build # 注意：npm run build 需在 docs/package.json 中定义 # "scripts": { "build": "vuepress build ." } - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/dist # VuePress 默认输出到 docs/dist/ publish_branch: gh-pages # 部署到 gh-pages 分支 cname: docs.my-sdk.com # 如果有自定义域名

关键配置点：

  • fetch-depth: 0是必须的，否则git push会因缺少历史记录失败；
  • publish_dir必须指向docs/dist/，因为 VuePress 构建默认输出到docs/.vuepress/dist/，但我们在config.js中设置了dest: 'dist'；
  • cname文件需在docs/public/目录下创建，内容为你的域名，VuePress 会自动将其复制到dist/根目录。

6.3 主题定制：从零创建一个轻量级主题

不要迷信第三方主题。一个精简的主题，代码量往往不到 500 行，却能完美匹配你的品牌。以下是创建最小可行主题的步骤：

# 在 docs/.vuepress/ 下创建主题目录 mkdir -p themes/my-theme # 创建主题入口 echo "module.exports = (options, ctx) => ({})" > themes/my-theme/index.js # 创建布局组件 cat > themes/my-theme/layouts/Layout.vue << 'EOF' <template> <div class="my-theme-container"> <header class="my-theme-header"> <router-link to="/"><img :src="$withBase('/logo.png')" alt="Logo"></router-link> <nav class="my-theme-nav"> <router-link v-for="item in $themeConfig.nav" :key="item.text" :to="item.link">{{ item.text }}</router-link> </nav> </header> <main class="my-theme-main"> <Content /> </main> <footer class="my-theme-footer"> &copy; {{ new Date().getFullYear() }} My SDK </footer> </div> </template> <script> export default { name: 'Layout' } </script> <style> .my-theme-container { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto; } .my-theme-header { background: #2c3e50; color: white; padding: 1rem; } .my-theme-nav a { color: #ecf0f1; margin-right: 1rem; text-decoration: none; } .my-theme-main { max-width: 800px; margin: 0 auto; padding: 2rem; } .my-theme-footer { text-align: center; padding: 1rem; border-top: 1px solid #eee; } </style> EOF

然后在config.js中启用：

module.exports = { theme: './.vuepress/themes/my-theme', // 相对路径指向自定义主题 themeConfig: { nav: [ { text: '首页', link: '/' }, { text: '指南', link: '/guide/' } ] } }

这个主题只有 3 个文件（index.js、Layout.vue、logo.png），却完全替代了@vuepress/theme-default。它没有侧边栏、没有搜索、没有返回顶部，但足够轻量、完全可控、易于维护。当你需要添加新功能时，再逐步引入插件，而不是一开始就被庞大主题绑架。

6.4 性能优化：让文档加载快如闪电

文档站的性能，直接影响用户留存。VuePress 默认已做很多优化，但仍有提升空间：

  1. 代码分割（Code Splitting）：VuePress 2 默认启用，无需配置；
  2. 图片懒加载：在config.js中启用@vuepress/plugin-medium-zoom插件，它会自动为<img>添加loading="lazy"；
  3. 字体优化：在config.js的head中预加载关键字体：
head: [ ['link', { rel: 'preload', as: 'font', href: '/fonts/inter.woff2', type: 'font/woff2', crossorigin: 'anonymous' }] ]
  1. 移除未用 CSS：使用critters插件提取首屏关键 CSS：
npm install -D critters
// .vuepress/config.js const { createCritters } = require('critters') module.exports = { configureWebpack: (config) => { if (process.env.NODE_ENV === 'production') { config.plugins.push( createCritters({ preload: 'media', reduceInlineStyles: false }) ) } } }

实测数据：某 SDK 文档站（约 120 个页面）在开启上述优化后，Lighthouse 性能评分从 68 提升到 92，首屏加载时间从 1.8s 降至 0.6s。

最后分享一个血泪教训：永远不要在docs/.vuepress/config.js中写console.log()。它会在构建时输出到控制台，看似无害，但在 CI 环境中可能导致日志截断、构建超时，甚至被某些安全扫描工具误判为恶意行为。调试用console.warn()或写入临时文件，上线前务必清理所有console.*。

我在实际使用中发现，VuePress 的真正价值不在它“能做什么”，而在它“不强迫你做什么”。它不规定你必须用 Markdown 写文档，你可以用.vue文件写交互式教程；它不强制你用它的主题，你可以用 Tailwind CSS 从零构建 UI；它不锁死你的构建流程，你可以用插件接入任何 Node.js 工具链。它像一个沉默的搭档，当你需要简单时，它给你开箱即用的config.js；当你需要复杂时，它给你完整的 Vue 生态和可编程的构建流水线。这种自由度，正是它在技术文档领域屹立不倒的核心原因。

http://www.gsyq.cn/news/1571360.html

相关文章：

  • LangGraph ReAct Agent五层执行机制深度解析
  • 逻辑博弈与修正SHAP：让特征归因更严谨、更可信的工程实践
  • 2026防城港漏水检测维修精选优质服务商TOP5推荐！卫生间漏水/厨房漏水/屋顶天花板漏水/阳台漏水/地下室漏水防水补漏检测维修-正规防水补漏公司优选口碑榜测评推荐 - 即刻修防水
  • OpenClaw Skills深度解析：构建可调试的AI能力契约
  • Prompt Caching原理与实战：降低LLM API成本40%+的关键技术
  • Transformer架构深度解析：从原理设计到工程落地
  • Gemini 3.5 Flash：企业级AI服务的确定性交付范式
  • Codex Desktop本地AI工作流配置核心：auth.json与config.toml协同原理
  • 2026 江苏泰州市全域彩钢瓦翻新修缮 TOP4 权威推荐｜沿江盐雾厂房金属屋面防水除锈喷漆企业对比 + 厂房业主避坑指南 - 本地便民网
  • 自蒸馏技术：通过高维流形对齐恢复大语言模型通用能力
  • DeepSeek V4 Flash：大模型推理的硬件级成本革命
  • 微信聊天记录永久保存终极指南：免费工具WeChatExporter完整使用教程
  • 如何用3个核心功能提升英雄联盟游戏体验：League Akari工具全解析
  • EVIL算法：用LLM引导进化搜索攻克时序数据零样本推理难题
  • PHP反序列化进阶攻防：属性类型混淆、CVE绕过与字符串逃逸漏洞深度解析
  • Django Models 入门：从数据库建模到业务逻辑封装
  • 基于鞍点法的稀疏VLSF码优化：提升短包通信效率与可靠性
  • Qwen2.5-VL：多模态知识框架与视觉token化原理
  • GLM-5V-Turbo：原生多模态Agent基座模型解析
  • Kimi K2.5：原生多模态智能体的架构革命
  • exit() 函数深度解析：从C++退出码到Docker报错的底层机制
  • 5个颠覆性技巧：用Xournal++彻底改变你的笔记工作流
  • AI编程最后一公里：从生成代码到生产就绪的7步护航体系
  • WebAssembly与资源限制：C++程序的沙箱化运行
  • DEIMv2：基于DINOV3的轻量视觉适配方法
  • 2026镇江本地人必选防水补漏检测维修公司靠谱服务商TOP5推荐：房屋渗漏水检测维修/卫生间/厨房/天花板/阳台/外墙渗漏水检测补漏维修-暗管漏水检测专业仪器精准定位漏水点 - 即刻修防水
  • 音乐歌词下载终极教程：免费批量获取网易云和QQ音乐LRC歌词
  • 2026 江苏盐城市全域彩钢瓦翻新修缮 TOP4 权威推荐｜沿海盐雾厂房金属屋面防水除锈喷漆企业对比 + 滨海专属避坑指南 - 本地便民网
  • 2026 江苏苏州全域彩钢瓦翻新修缮 TOP4 权威推荐｜厂房金属屋面防水除锈喷漆公司对比 + 行业避坑指南 - 本地便民网
  • 从GAM到MoE：可解释AI的架构演进与工程实践