VuePress 2.0

VuePress 是一个由 Vue 驱动的静态网站生成器，它融合了 Markdown 的简洁写作体验与 Vue 的灵活开发能力，既支持快速搭建轻量级文档站点，也能通过自定义配置满足复杂的个性化需求，同时兼顾静态页面的高性能加载与单页应用（SPA）的流畅交互体验。

官网【中文】

自行前往：https://vuepress.vuejs.org/zh/#/
点击前往：🔗点我

快速构建

VuePress 2.0 的快速构建流程基于 npm/yarn/pnpm 包管理器，步骤简洁且可复用，适合新手快速上手。

1. 环境准备

本教程选用pnpm Node.js 包管理器

首先确保本地已安装以下环境：

• Node.js 14.18+（VuePress 2.0 最低依赖版本）
• pnpm（包管理器，需提前先安装](https://pnpm.io/zh/installation)）

可通过以下命令验证环境：

# 查看 Node.js 版本
node -v
# 查看 pnpm 版本
pnpm -v

若未安装相关环境，需先进行安装：

• Node.js：从 Node.js 官网 下载对应系统版本并安装
• pnpm：安装完成 Node.js 后，执行 npm install -g pnpm 全局安装 pnpm（或参考 pnpm 官网的其他安装方式）

2. 初始化项目

选择一个本地文件夹作为项目根目录，通过终端执行以下命令初始化项目（使用pnpm）：

# 1. 使用 pnpm create 快速创建 VuePress 项目（项目名：comet）
pnpm create vuepress comet

# 2. 进入项目文件夹
cd comet

• pnpm create vuepress 是 VuePress 官方提供的快速初始化命令；
• comet 为项目名称，可根据实际需求修改。

3. 配置启动脚本

项目初始化后，package.json 文件会自动生成基础脚本，可根据需要补充完善：

{
  "scripts": {
    "docs:dev": "vuepress dev docs",  // 本地开发预览（热更新）
    "docs:build": "vuepress build docs",  // 打包生成静态文件
    "docs:clean-dev": "vuepress dev docs --clean-cache"  // 清除缓存后启动开发服务器
  }
}

5. 启动与预览

执行本地开发命令，启动项目并预览效果：

pnpm run docs:dev

6. 打包部署（可选）

若需将站点部署到服务器/静态托管平台，执行打包命令：

pnpm run docs:build

修改配置

VuePress 2.0 的配置通过 docs/.vuepress/config.js（或 config.ts）文件管理，支持导航栏、侧边栏、站点信息等核心功能的自定义，以下是高频配置项的详细说明。

基础配置文件创建

首先在 docs 文件夹下创建 .vuepress 子文件夹（配置文件存放目录），然后在 .vuepress 中创建 config.js 文件，基础结构如下：

// docs/.vuepress/config.js
import { defineUserConfig } from 'vuepress'

// 导出 VuePress 配置
export default defineUserConfig({
  // 站点基础信息
  title: '我的 VuePress 文档',  // 站点标题（浏览器标签页显示）
  description: '基于 VuePress 2.0 构建的个人文档站点',  // 站点描述（SEO 用）
  base: '/',  // 站点基础路径（默认 '/'，若部署到子路径需修改，如 GitHub Pages 子仓库需设为 '/仓库名/'）

  // 主题配置（默认主题）
  themeConfig: {
    // 导航栏、侧边栏等配置写在这里
  }
})

• defineUserConfig：VuePress 2.0 提供的类型安全配置函数，帮助开发者规避语法错误；
• 所有配置修改后，需重启 npm run docs:dev 或等待热更新生效。

修改 导航栏

导航栏（Navbar）位于页面顶部，支持 logo、菜单、链接、下拉列表等元素，配置均在 themeConfig.navbar 中定义。

1. 基础导航菜单

添加顶部一级菜单，点击跳转至对应文档页面：

themeConfig: {
  navbar: [
    // 1. 首页（默认链接到 docs/README.md）
    { text: '首页', link: '/' },

    // 2. 普通菜单（链接到 docs/guide/README.md）
    { text: '使用指南', link: '/guide/' },

    // 3. 外部链接（添加 target: '_blank' 实现新窗口打开）
    { text: 'Vue 官网', link: 'https://vuejs.org/', target: '_blank' }
  ]
}

• 链接路径规则：/guide/ 对应 docs/guide/README.md，/guide/install.md 对应 docs/guide/install.md；
• 外部链接需写完整 URL（如 https://xxx），内部链接使用相对路径（以 / 开头）。

2. 下拉列表菜单

当菜单包含多个子项时，可配置下拉列表：

themeConfig: {
  navbar: [
    {
      text: '进阶功能',  // 下拉列表标题
      items: [
        { text: '主题定制', link: '/advanced/theme/' },
        { text: '插件使用', link: '/advanced/plugin/' },
        { text: '打包配置', link: '/advanced/build/' }
      ]
    }
  ]
}

• items 数组内的每个对象对应一个下拉选项，支持内部/外部链接。

3. 导航栏 Logo

添加站点 logo（位于导航栏左侧），需先将 logo 图片放入 docs/.vuepress/public 文件夹（静态资源目录，该文件夹下的文件可直接通过 /文件名 访问）：

themeConfig: {
  // 导航栏 Logo（支持相对路径和绝对路径）
  logo: '/logo.png',  // 对应 docs/.vuepress/public/logo.png
  logoAlt: '站点 Logo',  // 图片加载失败时的替代文本（无障碍访问）

  navbar: [/* 其他导航配置 */]
}

4. 响应式适配

VuePress 默认主题的导航栏在移动端会自动折叠为“汉堡菜单”（点击展开），无需额外配置；若需隐藏某菜单在移动端的显示，可添加 mobile: false：

{
  text: '桌面端专属菜单',
  link: '/desktop/',
  mobile: false  // 移动端不显示该菜单
}

修改 侧边栏

侧边栏（Sidebar）位于页面左侧，用于展示当前文档目录的层级结构，支持按页面、按目录分组配置，配置在 themeConfig.sidebar 中定义。

1. 全局统一侧边栏

若所有页面使用相同的侧边栏，直接将 sidebar 设为一个数组，数组内每个对象对应一个侧边栏项：

themeConfig: {
  sidebar: [
    // 1. 一级标题（无链接，仅作为分组标题）
    {
      text: '基础入门',
      collapsible: true,  // 是否可折叠（默认 false，展开状态）
      items: [
        { text: '环境准备', link: '/guide/env/' },  // 子项 1
        { text: '快速构建', link: '/guide/quick-start/' }  // 子项 2
      ]
    },
    // 2. 二级标题（直接链接到页面）
    { text: '配置详解', link: '/config/' },
    // 3. 嵌套分组（支持多级嵌套）
    {
      text: '进阶功能',
      collapsible: true,
      items: [
        { text: '主题定制', link: '/advanced/theme/' },
        {
          text: '插件相关',
          collapsible: true,
          items: [
            { text: '插件安装', link: '/advanced/plugin/install/' },
            { text: '常用插件', link: '/advanced/plugin/recommend/' }
          ]
        }
      ]
    }
  ]
}

• collapsible: true：允许该分组折叠/展开，适合内容较多的场景；
• 嵌套分组：items 数组内可继续嵌套 { text, items } 结构，实现多级目录。

2. 按目录分组侧边栏

若不同目录（如 /guide/ 和 /advanced/）需要不同的侧边栏，可将 sidebar 设为一个对象，键为目录路径，值为该目录的侧边栏配置：

themeConfig: {
  sidebar: {
    // 1. /guide/ 目录的侧边栏
    '/guide/': [
      { text: '环境准备', link: '/guide/env/' },
      { text: '快速构建', link: '/guide/quick-start/' }
    ],

    // 2. /advanced/ 目录的侧边栏
    '/advanced/': [
      { text: '主题定制', link: '/advanced/theme/' },
      { text: '插件使用', link: '/advanced/plugin/' }
    ],

    // 3. 首页（/）无侧边栏（设为 [] 即可）
    '/': []
  }
}

• 路径匹配规则：/guide/ 会匹配所有以 /guide/ 开头的页面（如 /guide/env.html、/guide/quick-start.html）；
• 未匹配到路径的页面，会使用默认的全局侧边栏（若未配置则不显示侧边栏）。

3. 自动生成侧边栏（基于 Markdown 标题）

若不想手动配置侧边栏，可使用 VuePress 2.0 的 自动侧边栏功能，通过 @vuepress/plugin-auto-sidebar 插件实现（需额外安装）：

1. 安装插件：

   pnpm add @vuepress/plugin-auto-sidebar@next -D
   

2. 在 config.js 中配置插件：

   import { defineUserConfig } from 'vuepress'
   import autoSidebarPlugin from '@vuepress/plugin-auto-sidebar'
   
   export default defineUserConfig({
     plugins: [
       autoSidebarPlugin({
         // 配置项：按目录自动生成侧边栏
         sidebarDepth: 2,  // 提取 Markdown 中 1-2 级标题作为侧边栏项
         collapse: true  // 自动折叠非当前页面的分组
       })
     ],
     themeConfig: {
       // 无需手动配置 sidebar，插件会自动生成
     }
   })
   

• 该插件适合文档结构清晰、依赖 Markdown 标题层级的场景，减少手动配置工作量。

4. 侧边栏样式调整

默认主题的侧边栏支持简单样式修改，例如调整宽度、高亮颜色等，需在 docs/.vuepress/styles/index.scss 文件中添加自定义 CSS（VuePress 2.0 支持 SCSS 预处理器）：

// docs/.vuepress/styles/index.scss
// 调整侧边栏宽度（默认 240px）
$sidebar-width: 280px;

// 调整当前激活侧边栏项的颜色
.sidebar-link.active {
  color: #42b983 !important;  // Vue 品牌绿
}

• index.scss 是 VuePress 默认的全局样式文件，修改后会覆盖默认样式。