VitePress 学习指南

主题

主题开发工具 ​

工欲善其事，必先利其器。本文档将介绍 VitePress 主题开发中常用的工具、插件和配置，帮助你提高开发效率。

版本说明

  • 本文档基于 VitePress v1.0.0+ 编写
  • 推荐使用 VS Code 作为主要开发工具
  • 列出工具均为免费或开源工具

VS Code 扩展 ​

必备扩展 ​

1. Vue - Official (Vue Language Features, Volar) ​

json
// 扩展 ID
Vue.volar

功能：

  • Vue 3 语法高亮
  • TypeScript 支持
  • 智能提示
  • 错误检测

2. VitePress Snippets ​

json
// 扩展 ID
dingyi.code-snippets

功能：

  • VitePress 代码片段
  • 快速创建模板
  • 提高编码效率

3. Markdown All in One ​

json
// 扩展 ID
yzhang.markdown-all-in-one

功能：

  • Markdown 快捷键
  • 实时预览
  • 目录生成

4. MDX ​

json
// 扩展 ID
unifiedjs.vscode-mdx

功能：

  • MDX 语法支持
  • JSX 高亮

推荐扩展 ​

5. ESLint ​

json
// 扩展 ID
dbaeumer.vscode-eslint

功能：

  • JavaScript/TypeScript 代码检查
  • 自动修复

6. Prettier ​

json
// 扩展 ID
esbenp.prettier-vscode

功能：

  • 代码格式化
  • 支持多种语言

7. Tailwind CSS IntelliSense ​

json
// 扩展 ID
bradlc.vscode-tailwindcss

功能：

  • Tailwind CSS 智能提示
  • 类名自动补全

8. Error Lens ​

json
// 扩展 ID
usernamehw.errorlens

功能：

  • 行内显示错误
  • 快速定位问题

9. Path Intellisense ​

json
// 扩展 ID
christian-kohler.path-intellisense

功能：

  • 路径自动补全
  • 图片路径提示

10. Auto Rename Tag ​

json
// 扩展 ID
formulahendry.auto-rename-tag

功能：

  • 自动重命名配对标签
  • HTML/Vue 标签修改

VS Code 配置 ​

json
// .vscode/settings.json
{
  // 编辑器设置
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  
  // Vue 设置
  "[vue]": {
    "editor.defaultFormatter": "Vue.volar"
  },
  
  // TypeScript 设置
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  
  // Markdown 设置
  "[markdown]": {
    "editor.defaultFormatter": "yzhang.markdown-all-in-one",
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
      "other": true,
      "comments": false,
      "strings": true
    }
  },
  
  // 文件关联
  "files.associations": {
    "*.md": "markdown",
    "*.vue": "vue"
  },
  
  // Volar 设置
  "volar.takeOverMode.enabled": true,
  "volar.completion.preferredTagNameCase": "kebab",
  "volar.completion.preferredAttrNameCase": "kebab"
}
json
// .vscode/extensions.json
{
  "recommendations": [
    "Vue.volar",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "yzhang.markdown-all-in-one",
    "usernamehw.errorlens"
  ]
}

代码质量工具 ​

ESLint 配置 ​

bash
# 安装依赖
npm install -D eslint @eslint/js typescript-eslint eslint-plugin-vue
javascript
// eslint.config.js
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import vue from 'eslint-plugin-vue'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.vue'],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser
      }
    }
  },
  {
    rules: {
      // 自定义规则
      'vue/multi-word-component-names': 'off',
      'vue/no-v-html': 'warn',
      '@typescript-eslint/no-unused-vars': 'error',
      '@typescript-eslint/no-explicit-any': 'warn'
    }
  },
  {
    ignores: [
      'node_modules/**',
      'dist/**',
      '.vitepress/dist/**',
      '.vitepress/cache/**'
    ]
  }
]

Prettier 配置 ​

bash
# 安装依赖
npm install -D prettier eslint-config-prettier
json
// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "none",
  "printWidth": 100,
  "vueIndentScriptAndStyle": true,
  "endOfLine": "lf"
}
json
// .prettierignore
node_modules
dist
.vitepress/dist
.vitepress/cache
*.md

TypeScript 配置 ​

json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "importHelpers": true,
    "experimentalDecorators": true,
    "strictFunctionTypes": true,
    "noImplicitAny": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["vitepress/client"],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": [
    ".vitepress/**/*.ts",
    ".vitepress/**/*.vue",
    "src/**/*.ts",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

开发工具 ​

Vite 插件 ​

1. vite-plugin-inspect ​

bash
npm install -D vite-plugin-inspect
typescript
// .vitepress/config.ts
import Inspect from 'vite-plugin-inspect'

export default defineConfig({
  vite: {
    plugins: [
      Inspect() // http://localhost:5173/__inspect/
    ]
  }
})

2. vite-plugin-vue-devtools ​

bash
npm install -D vite-plugin-vue-devtools
typescript
// .vitepress/config.ts
import VueDevTools from 'vite-plugin-vue-devtools'

export default defineConfig({
  vite: {
    plugins: [
      VueDevTools()
    ]
  }
})

3. vite-plugin-compression ​

bash
npm install -D vite-plugin-compression
typescript
// .vitepress/config.ts
import viteCompression from 'vite-plugin-compression'

export default defineConfig({
  vite: {
    plugins: [
      viteCompression({
        algorithm: 'gzip',
        ext: '.gz'
      })
    ]
  }
})

Markdown 插件 ​

1. markdown-it-katex ​

bash
npm install -D markdown-it-katex
typescript
// .vitepress/config.ts
import katex from 'markdown-it-katex'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(katex)
    }
  }
})

2. markdown-it-emoji ​

bash
npm install -D markdown-it-emoji
typescript
// .vitepress/config.ts
import emoji from 'markdown-it-emoji'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(emoji)
    }
  }
})

图标工具 ​

1. Iconify ​

bash
npm install -D @iconify/json @iconify/utils
typescript
// 使用图标
import { icons } from '@iconify/json'

// 在配置中使用
{
  text: '🏠 首页',
  link: '/'
}

2. unplugin-icons ​

bash
npm install -D unplugin-icons
typescript
// .vitepress/config.ts
import Icons from 'unplugin-icons/vite'

export default defineConfig({
  vite: {
    plugins: [
      Icons({
        compiler: 'vue3',
        autoInstall: true
      })
    ]
  }
})
vue
<!-- 使用 -->
<script setup>
import IconHome from '~icons/mdi/home'
</script>

<template>
  <IconHome />
</template>

调试工具 ​

Vue DevTools ​

bash
# 浏览器扩展
# Chrome: https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd
# Firefox: https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/

功能：

  • 组件树查看
  • 状态调试
  • 性能分析
  • 路由检查

Chrome DevTools ​

快捷键 ​

F12 - 打开开发者工具
Ctrl+Shift+I (Mac: Cmd+Opt+I) - 打开开发者工具
Ctrl+Shift+C (Mac: Cmd+Opt+C) - 元素选择器
Ctrl+Shift+J (Mac: Cmd+Opt+J) - 控制台
Ctrl+Shift+M (Mac: Cmd+Opt+M) - 设备模拟

有用的控制台命令 ​

javascript
// 查看当前页面信息
console.log('当前路径:', window.location.pathname)

// 性能分析
console.time('操作')
// ... 执行代码
console.timeEnd('操作')

// 查看所有 Vue 实例
document.querySelectorAll('[data-v-app]')

// 检查内存使用
console.log('内存使用:', performance.memory)

命令行工具 ​

concurrently ​

并行运行多个命令：

bash
npm install -D concurrently
json
// package.json
{
  "scripts": {
    "dev": "concurrently \"npm run dev:vite\" \"npm run dev:theme\"",
    "dev:vite": "vitepress dev",
    "dev:theme": "vite build --watch"
  }
}

nodemon ​

监听文件变化：

bash
npm install -D nodemon
json
// package.json
{
  "scripts": {
    "dev:watch": "nodemon --watch .vitepress --exec 'vitepress dev'"
  }
}

rimraf ​

跨平台删除：

bash
npm install -D rimraf
json
// package.json
{
  "scripts": {
    "clean": "rimraf dist .vitepress/dist .vitepress/cache"
  }
}

实用脚本 ​

自动生成页面 ​

javascript
// scripts/create-page.js
import fs from 'fs'
import path from 'path'
import readline from 'readline'

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
})

rl.question('页面标题: ', (title) => {
  const fileName = title
    .toLowerCase()
    .replace(/\s+/g, '-')
    .replace(/[^\w-]/g, '')
  
  const content = `---
title: ${title}
---

# ${title}

内容...
`
  
  const filePath = path.join(process.cwd(), 'docs', `${fileName}.md`)
  
  fs.writeFileSync(filePath, content)
  console.log(`✅ 页面已创建: ${filePath}`)
  
  rl.close()
})

批量处理图片 ​

javascript
// scripts/optimize-images.js
import sharp from 'sharp'
import glob from 'fast-glob'

async function optimizeImages() {
  const images = await glob('docs/public/**/*.{jpg,jpeg,png}')
  
  for (const image of images) {
    const outputPath = image.replace(/\.(jpg|jpeg|png)$/, '.webp')
    
    await sharp(image)
      .webp({ quality: 80 })
      .toFile(outputPath)
    
    console.log(`✅ 已优化: ${outputPath}`)
  }
}

optimizeImages()

生成 sitemap ​

javascript
// scripts/generate-sitemap.js
import fs from 'fs'
import glob from 'fast-glob'

async function generateSitemap() {
  const pages = await glob('docs/**/*.md')
  const urls = pages
    .map(page => page
      .replace('docs/', '/')
      .replace('.md', '/')
      .replace('/index/', '/')
    )
    .filter(url => !url.includes('__tests__'))
  
  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls.map(url => `  <url>
    <loc>https://your-domain.com${url}</loc>
    <lastmod>${new Date().toISOString().split('T')[0]}</lastmod>
  </url>`).join('\n')}
</urlset>`
  
  fs.writeFileSync('docs/public/sitemap.xml', sitemap)
  console.log('✅ Sitemap 已生成')
}

generateSitemap()

包管理器 ​

npm ​

bash
# 常用命令
npm install                 # 安装依赖
npm install package-name    # 安装包
npm install -D package-name # 安装开发依赖
npm update                  # 更新依赖
npm outdated                # 检查过期依赖
npm audit                   # 安全审计
npm run script-name         # 运行脚本

pnpm（推荐） ​

bash
# 安装
npm install -g pnpm

# 常用命令
pnpm install                # 安装依赖
pnpm add package-name       # 安装包
pnpm add -D package-name    # 安装开发依赖
pnpm update                 # 更新依赖
pnpm outdated               # 检查过期依赖
pnpm audit                  # 安全审计

yarn ​

bash
# 常用命令
yarn                        # 安装依赖
yarn add package-name       # 安装包
yarn add -D package-name    # 安装开发依赖
yarn upgrade                # 更新依赖
yarn outdated               # 检查过期依赖

在线工具 ​

设计工具 ​

开发工具 ​

性能工具 ​

图标资源 ​

开发环境配置 ​

Node.js 版本管理 ​

nvm ​

bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 使用 nvm
nvm install 20       # 安装 Node.js 20
nvm use 20           # 切换到 Node.js 20
nvm alias default 20 # 设置默认版本

fnm ​

bash
# 安装 fnm
curl -fsSL https://fnm.vercel.app/install | bash

# 使用 fnm
fnm install 20
fnm use 20

环境变量 ​

bash
# .env
NODE_ENV=development
VITE_API_URL=http://localhost:3000
bash
# .env.production
NODE_ENV=production
VITE_API_URL=https://api.example.com
typescript
// 使用环境变量
const apiUrl = import.meta.env.VITE_API_URL

快捷键参考 ​

VS Code ​

Ctrl+P           - 快速打开文件
Ctrl+Shift+P     - 命令面板
Ctrl+`           - 打开终端
Ctrl+B           - 切换侧边栏
Ctrl+D           - 选择下一个匹配项
Ctrl+Shift+F     - 全局搜索
Ctrl+G           - 跳转到行
Alt+Up/Down      - 移动行
Ctrl+/           - 注释/取消注释
Ctrl+Shift+K     - 删除整行

Chrome DevTools ​

F12              - 打开开发者工具
Ctrl+Shift+C     - 元素选择器
Ctrl+Shift+J     - 控制台
Ctrl+Shift+M     - 设备模拟
Ctrl+R           - 刷新
Ctrl+Shift+R     - 强制刷新

相关资源 ​

下一步 ​

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南