环境要求

• Node.js：^20.6.0 或 >= 22.0.0
• 包管理器：npm 8+、pnpm 8+ 或 Yarn 2+

如何安装环境依赖？

1. 下载 Node.js

   访问 Node.js 官网 下载最新稳定版，按照安装向导完成安装（通常保持默认设置即可）。

2. 启用 PNPM

   安装完成后打开终端，执行以下命令：

   corepack enable

   我们推荐使用 pnpm 作为包管理器。

3. 环境就绪

命令行安装 推荐

我们提供了命令行工具，可快速搭建基础项目结构。执行以下命令启动安装向导：

pnpm

pnpm create vuepress-theme-plume@latest

yarn

yarn create vuepress-theme-plume@latest

npm

npm create vuepress-theme-plume@latest

启动后只需回答几个简单问题即可完成配置：

┌  Welcome to VuePress and vuepress-theme-plume !
│
◇  Select a language to display / 选择显示语言
│  简体中文
│
◇  您想在哪里初始化 VuePress？
│  ./my-project
│
◇  站点名称：
│  My Vuepress Site
│
◇  站点描述信息：
│  My Vuepress Site Description
│
◇  是否使用多语言？
│  No
│
◇  请选择站点默认语言
│  简体中文
│
◇  是否使用 TypeScript？
│  Yes
│
◇  请选择打包工具
│  Vite
│
◇  部署方式：
│  Custom
│
◇  是否初始化 git 仓库？
│  Yes
│
◇  是否安装依赖？
│  Yes
│
◇   🎉 创建成功!
│
└  🔨 执行以下命令即可启动：
      cd ./my-project
      pnpm run docs:dev

命令行工具使用指南

以 Windows 系统为例：

1. 按下 Win + R 打开"运行"对话框
2. 输入 cmd 或 powershell 后按 Enter

如果当前目录不正确，可使用以下命令切换：

D:                    # 切换到 D 盘（根据实际情况调整）
cd open-source        # 进入目标目录

此时执行 pnpm create vuepress-theme-plume@latest 即可创建项目，项目将位于 D:\open-source\my-project 目录。

手动安装

注意事项

• 使用 pnpm 时需额外安装 vue 作为 peer-dependencies
• 使用 Yarn 2+ 时需在 .yarnrc.yml 中设置 nodeLinker: 'node-modules'

如需手动安装，请按以下步骤操作：

• 创建项目目录

  mkdir my-blog
  cd my-blog

• 初始化项目

  pnpm

  git init
  pnpm init

  yarn

  git init
  yarn init

  npm

  git init
  npm init

• 安装核心依赖

  安装 vuepress@next 和主题包：

  pnpm

  # 安装 VuePress
  pnpm add -D vuepress@next vue
  # 安装主题和构建工具
  pnpm add -D vuepress-theme-plume @vuepress/bundler-vite@next

  yarn

  # 安装 VuePress
  yarn add -D vuepress@next vue
  # 安装主题和构建工具
  yarn add -D vuepress-theme-plume @vuepress/bundler-vite@next

  npm

  # 安装 VuePress
  npm i -D vuepress@next vue
  # 安装主题和构建工具
  npm i -D vuepress-theme-plume @vuepress/bundler-vite@next

  版本兼容性

  当前主题已适配至 [email protected]，使用其他版本可能存在兼容性问题。

• 配置构建脚本

  在 package.json 中添加：

  package.json

  {
    "scripts": {
      "docs:dev": "vuepress dev docs",
      "docs:build": "vuepress build docs"
    }
  }

  VuePress 默认使用 docs 目录作为文档根目录。

• 配置 Git 忽略规则

  .gitignore

  node_modules
  .temp
  .cache

  sh

  echo 'node_modules' >> .gitignore
  echo '.temp' >> .gitignore
  echo '.cache' >> .gitignore

• 配置主题

  docs/.vuepress/config.ts

  import { 
  viteBundler
   } from '@vuepress/bundler-vite'
  import { 
  defineUserConfig
   } from 'vuepress'
  import { 
  plumeTheme
   } from 'vuepress-theme-plume'
  
  export default 
  defineUserConfig
  ({
    // 必须设置默认语言
    
  lang
  : 'zh-CN',
    
  theme
  : 
  plumeTheme
  ({
      // 主题配置...
    }),
    
  bundler
  : 
  viteBundler
  (),
  })

  语言配置必填

  无论是否使用多语言，都必须正确配置 lang 选项，主题依赖此设置确定文本语言环境。

• 创建首页文档

  README.md

  ---
  home: true
  ---

• 启动开发服务器

  pnpm

  pnpm docs:dev

  yarn

  yarn docs:dev

  npm

  npm run docs:dev

  VuePress 将在 http://localhost:8080 启动开发服务器，支持 Markdown 文件的热重载。

• 安装完成

主题更新

使用以下命令检查并更新主题：

pnpm

pnpm dlx vp-update

yarn

yarn dlx vp-update

npm

npx vp-update

贡献者

pengzhanbo

更新日志

2025/10/7 15:13

查看所有更新日志

• 4d236-feat(theme)!: add collections support (#704)于 2025/10/7
• bf9ef-docs: update docs于 2024/9/1