VuePress 搭建个人博客或技术文档网站的详细教程
原创
VuePress 搭建个人博客或技术文档网站的详细教程
原创
小焱
发布于 2025-08-08 22:14:40
发布于 2025-08-08 22:14:40
代码可运行
运行总次数：0
代码可运行
以下是使用 VuePress 搭建个人博客或技术文档网站的详细教程，涵盖基础搭建、配置优化和部署流程：
一、环境准备
- Node.js
- 确保已安装 Node.js（建议版本 ≥ 18.0，推荐 LTS 版本）。
- 验证安装：终端执行
node -v和npm -v，显示版本号即成功。
- 包管理器
- 使用
npm（v9.0+）、yarn或pnpm（推荐pnpm，速度快且节省磁盘空间）。
- 使用
二、基础搭建流程
1. 创建项目
bashmkdir vuepress-blog && cd vuepress-blognpm init -y # 生成 package.json2. 安装 VuePress
- 基础版（默认主题）：bashnpm install -D vuepress@next
- 美化版（推荐主题
vuepress-theme-reco）：bashnpm install -D vuepress-theme-reco@2.x
3. 项目结构
bashvuepress-blog/├── docs/ # 文档根目录│ ├── .vuepress/ # VuePress 配置目录│ │ ├── public/ # 静态资源（如图片、favicon）│ │ ├── config.js # 主配置文件│ │ └── styles/ # 自定义样式（可选）│ └── README.md # 首页或默认页面└── package.json4. 初始化文档
在 docs/README.md 中写入内容：
markdown# Hello VuePress!> 这是一个简单的 VuePress 博客示例。5. 配置 package.json
添加启动脚本：
json{ "scripts": { "dev": "vuepress dev docs", "build": "vuepress build docs" }}三、核心配置
1. 基础配置 (docs/.vuepress/config.js)
javascriptimport { defineUserConfig } from 'vuepress';import { defaultTheme } from '@vuepress/theme-default'; export default defineUserConfig({ lang: 'zh-CN', title: '我的博客', description: 'VuePress 搭建的静态博客', theme: defaultTheme({ logo: '/images/logo.png', // 左上角 logo navbar: [ // 顶部导航栏 { text: '首页', link: '/' }, { text: 'GitHub', link: 'https://github.com/yourname' } ], sidebar: { // 侧边栏配置 '/guide/': [ { text: '快速入门', link: '/guide/' }, { text: '进阶配置', link: '/guide/advanced.md' } ] } })});2. 首页配置 (docs/README.md)
使用 YAML 前缀自定义首页：
markdown---home: trueheroText: VuePress 博客tagline: 简洁、高效、Vue 驱动actions: - text: 开始阅读 → link: /guide/features: - title: Markdown 优先 details: 以 Markdown 为中心的项目结构，专注写作。 - title: Vue 驱动 details: 支持在 Markdown 中使用 Vue 组件。 - title: 高性能 details: 预渲染静态 HTML + SPA 加载。footer: MIT Licensed | Copyright © 2025-present YourName---3. 静态资源
- 将图片（如
logo.png、avatar.jpg）放入docs/.vuepress/public/images/。 - 在 Markdown 中引用：markdown
四、主题与插件
1. 使用第三方主题
以 vuepress-theme-reco 为例：
javascript// config.jsimport themeReco from 'vuepress-theme-reco'; export default defineUserConfig({ theme: themeReco({ style: '@vuepress-reco/style-default', logo: '/images/logo.png', nav: [ { text: '首页', link: '/' }, { text: '分类', link: '/categories/' } ], // 更多配置参考主题文档 })});2. 常用插件
- 搜索增强： bashnpm install -D @vuepress/plugin-search@next 配置： javascriptplugins: [ ['@vuepress/search', { searchMaxSuggestions: 10 }]]
- 动态标题： bashnpm install -D vuepress-plugin-dynamic-title 配置： javascriptplugins: [ ['dynamic-title', { showText: '← 回来啦！' }]]
五、本地开发与构建
- 启动开发服务器：bashnpm run dev
- 访问
http://localhost:8080查看效果。
- 访问
- 生产构建：bashnpm run build
- 生成静态文件到
docs/.vuepress/dist/。
- 生成静态文件到
六、部署到 GitHub Pages
1. 配置基础路径
在 config.js 中添加：
javascriptexport default defineUserConfig({ base: '/repository-name/', // GitHub 仓库名（如 /vuepress-blog/）});2. 创建 GitHub Actions 部署脚本
在项目根目录创建 .github/workflows/deploy.yml：
yamlname: Deployon: push: branches: [main]jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - run: npm install - run: npm run build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/.vuepress/dist3. 配置 GitHub Pages
- 推送代码到 GitHub 仓库。
- 进入仓库 Settings → Pages：
- Source 选择
gh-pages分支，目录为/(root)。
- Source 选择
- 保存后，访问
https://yourname.github.io/repository-name/。
七、常见问题
- 图片加载失败
- 确保图片路径为绝对路径（如
/images/logo.png），并放在public/目录。
- 确保图片路径为绝对路径（如
- 样式覆盖
- 在
docs/.vuepress/styles/index.scss中自定义样式：scss:root { --accent-color: #42b983;}
- 在
- 部署后 404
- 检查
base路径是否与仓库名一致。 - 确保 GitHub Pages 设置指向
gh-pages分支。
- 检查
八、进阶优化
- 自定义主题：通过修改
docs/.vuepress/theme/Layout.vue实现。 - 评论系统：集成
Giscus或Valine。 - SEO 优化：在
config.js中配置head标签：javascripthead: [ ['meta', { name: 'keywords', content: 'VuePress,博客,技术文档' }], ['link', { rel: 'icon', href: '/images/logo.png' }]]
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
评论
登录后参与评论
推荐阅读
目录
腾讯云开发者
