快速开始
本指南将帮助你快速搭建和运行VuePress项目博客。
🛠️ 环境准备
系统要求
- Node.js: 16.0.0 或更高版本
- 包管理器: 推荐使用 PNPM，也支持 NPM 和 Yarn
- Git: 用于版本控制和部署
安装 Node.js
# 使用 Node Version Manager (推荐)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
nvm use node
# 验证安装
node --version # 应该显示 v16.0.0 或更高
npm --version
安装 PNPM
# 安装 PNPM
npm install -g pnpm
# 验证安装
pnpm --version
📦 项目创建
方法一：使用模板（推荐）
# 克隆项目模板
git clone https://github.com/your-username/vuepress-blog.git my-blog
cd my-blog
# 安装依赖
pnpm install
# 启动开发服务器
pnpm docs:dev
方法二：从零开始
# 创建项目目录
mkdir my-vuepress-blog
cd my-vuepress-blog
# 初始化项目
pnpm init
# 安装 VuePress
pnpm add -D vuepress@next @vuepress/bundler-vite@next @vuepress/theme-default@next
# 创建基本的项目结构
mkdir -p docs/.vuepress
🏗️ 项目结构
my-blog/
├── docs/ # 文档源文件
│ ├── .vuepress/ # VuePress 配置
│ │ ├── components/ # Vue 组件
│ │ ├── public/ # 静态资源
│ │ ├── styles/ # 样式文件
│ │ ├── config.js # 主配置文件
│ │ └── client.js # 客户端配置
│ ├── blog/ # 博客文章
│ ├── docs/ # 文档页面
│ └── README.md # 首页
├── .github/ # GitHub 配置
│ └── workflows/ # GitHub Actions
├── package.json # 项目配置
├── pnpm-lock.yaml # 依赖锁定
└── README.md # 项目说明
⚙️ 基本配置
创建配置文件
创建 docs/.vuepress/config.js：
import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'
export default defineUserConfig({
// 站点配置
lang: 'zh-CN',
title: '我的博客',
description: '分享技术，记录成长',
// 主题配置
theme: defaultTheme({
navbar: [
{ text: '首页', link: '/' },
{ text: '博客', link: '/blog/' },
{ text: '关于', link: '/about/' },
],
}),
})
创建首页
创建 docs/README.md：
---
home: true
heroText: 欢迎来到我的博客
tagline: 分享技术，记录成长
actions:
- text: 开始阅读
link: /blog/
type: primary
---
## 最新文章
- [VuePress 2.x 完全指南](./blog/vuepress-guide.md)
- [自动化部署实战](./blog/automated-deployment.md)
🚀 常用命令
# 开发模式
pnpm docs:dev # 启动开发服务器
pnpm docs:dev --port 8080 # 指定端口
# 构建
pnpm docs:build # 构建生产版本
pnpm docs:preview # 预览构建结果
# 部署
pnpm deploy # 执行部署脚本
🎨 自定义样式
创建样式文件
创建 docs/.vuepress/styles/index.scss：
// 自定义 CSS 变量
:root {
--c-brand: #42b883;
--c-brand-light: #42b883;
--font-family: 'Noto Sans SC', sans-serif;
}
// 自定义组件样式
.my-component {
padding: 1rem;
border-radius: 8px;
background: var(--c-bg-lighter);
}
使用自定义组件
创建 docs/.vuepress/components/MyComponent.vue：
<template>
<div class="my-component">
<h3>{{ title }}</h3>
<p>{{ content }}</p>
</div>
</template>
<script setup>
defineProps({
title: String,
content: String,
})
</script>
在Markdown中使用：
<MyComponent title="标题" content="内容" />
🔍 添加搜索功能
安装搜索插件：
pnpm add -D @vuepress/plugin-search@next
在配置中添加：
import { searchPlugin } from '@vuepress/plugin-search'
export default defineUserConfig({
plugins: [
searchPlugin({
locales: {
'/': {
placeholder: '搜索文档',
},
},
}),
],
})
📱 响应式设计
VuePress默认主题已经内置了响应式设计，但你也可以自定义响应式样式：
// 移动端优化
@media (max-width: 768px) {
.navbar {
padding: 0.5rem 1rem;
}
.sidebar {
transform: translateX(-100%);
}
}
🎯 下一步
现在你已经成功搭建了VuePress博客，接下来可以：
❓ 常见问题
Q: 开发服务器无法启动？
A: 检查端口是否被占用，或尝试使用 --port 参数指定其他端口。
Q: 构建失败？
A: 检查配置文件语法，确保所有依赖都已正确安装。
Q: 样式不生效？
A: 确认样式文件路径正确，并检查CSS语法是否正确。
Q: 如何添加新页面？
A: 在相应目录创建Markdown文件，然后在配置中添加导航链接。