VuePress 搭建静态博客及部署指南

什么是 VuePress？

VuePress 是一个基于 Vue.js 的静态网站生成器，它可以帮助你快速创建一个美观、响应式的静态博客或文档网站。相比于 Hexo，VuePress 拥有更简洁的配置和更现代的外观，同时还集成了 Vue.js 的强大功能。

如果你已经厌倦了 Hexo 的繁琐配置，或者想尝试一个新的博客系统，那么 VuePress 绝对值得一试！

一、安装和基本配置

1. 环境准备

首先，你需要确保你的电脑上已经安装了 Node.js（建议版本 10.0 或更高）。如果没有安装，可以去 Node.js 官网 下载安装。

2. 创建项目

打开命令行工具，执行以下命令来创建一个新的 VuePress 项目：

1
2
3
4
5
6
7
8
9
# 创建项目目录
mkdir my-vuepress-blog
cd my-vuepress-blog

# 初始化项目
npm init -y

# 安装 VuePress
npm install -D vuepress@next

3. 配置 package.json

打开 package.json 文件，添加以下脚本：

1
2
3
4
5
6
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

4. 创建基本目录结构

在项目根目录下创建 docs 文件夹，并在其中创建以下文件和目录：

1
2
3
4
5
6
7
my-vuepress-blog/
├── docs/
│   ├── .vuepress/
│   │   └── config.js
│   ├── README.md
│   └── posts/
└── package.json

5. 配置 config.js

在 .vuepress 文件夹下创建 config.js 文件，并添加以下基本配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
module.exports = {
  title: '我的博客',
  description: '这是一个使用 VuePress 搭建的博客',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '文章', link: '/posts/' },
      { text: '关于', link: '/about/' }
    ],
    sidebar: {
      '/posts/': [
        '',
        'first-post.md'
      ]
    }
  }
}

二、创建内容

1. 首页内容

打开 docs/README.md 文件，添加以下内容作为首页：

1
2
3
4
5
6
7
# 欢迎来到我的博客

这是一个使用 VuePress 搭建的博客。

## 最新文章

- [我的第一篇文章](/posts/first-post.md)

2. 创建文章

在 docs/posts/ 目录下创建你的第一篇文章 first-post.md：

1
2
3
4
5
6
7
# 我的第一篇文章

这是我使用 VuePress 写的第一篇文章。

## 什么是 VuePress？

VuePress 是一个基于 Vue.js 的静态网站生成器...

三、本地预览

现在，你可以通过以下命令在本地预览你的博客：

1
npm run docs:dev

然后打开浏览器，访问 http://localhost:8080 就可以看到你的博客了！

四、部署到 GitHub Pages

1. 创建 GitHub 仓库

首先，在 GitHub 上创建一个新的仓库，命名为 username.github.io（其中 username 是你的 GitHub 用户名）。

2. 配置 deploy.sh 脚本

在项目根目录下创建一个 deploy.sh 文件，添加以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
# 注意：这里需要修改为你自己的邮箱和用户名
# 这里我用了默认信息，你需要改成自己的
# git config user.email "you@example.com"
# git config user.name "Your Name"
git add -A
git commit -m 'deploy'

# 如果你想要部署到 https://USERNAME.github.io
git push -f git@github.com:USERNAME/USERNAME.github.io.git master

# 如果你想要部署到 https://USERNAME.github.io/REPO
# git push -f git@github.com:USERNAME/REPO.git master:gh-pages

cd -n

3. 修改 deploy.sh 中的信息

记得将脚本中的 USERNAME 替换为你自己的 GitHub 用户名，同时也可以取消注释并设置你自己的邮箱和用户名。

4. 运行部署脚本

在命令行中执行以下命令，为脚本添加执行权限并运行：

1
2
3
4
# Windows 用户可以直接运行 deploy.sh
# 或者在 Git Bash 中执行以下命令
chmod +x deploy.sh
./deploy.sh

稍等片刻，你的博客就会部署到 GitHub Pages 上了。过几分钟后，你就可以通过 https://USERNAME.github.io 访问你的博客了！

五、自定义主题和插件

1. 安装主题

VuePress 默认主题已经很好看了，但你也可以安装其他主题，比如 vuepress-theme-reco：

1
npm install -D vuepress-theme-reco@next

然后在 config.js 中配置：

1
2
3
4
5
6
7
module.exports = {
  // ...
  theme: 'reco',
  themeConfig: {
    // ...
  }
}

2. 安装插件

你还可以安装各种插件来增强你的博客功能，比如代码复制插件：

1
npm install -D vuepress-plugin-copy-code2

然后在 config.js 中配置：

1
2
3
4
5
6
module.exports = {
  // ...
  plugins: [
    'copy-code2'
  ]
}

六、常见问题

1. 部署失败

如果部署失败，可能是以下原因：

  • GitHub SSH 密钥没有配置好
  • 仓库名称不正确
  • 网络问题

可以检查错误信息，根据提示解决问题。

2. 页面不更新

如果修改了内容但页面没有更新，可能是缓存问题。可以尝试以下方法：

  • 清除浏览器缓存
  • 重新运行 npm run docs:build 和部署脚本

3. 自定义域名

如果你有自己的域名，可以在 docs/.vuepress/dist 目录下创建一个 CNAME 文件，内容为你的域名，然后重新部署。

七、总结

VuePress 是一个非常棒的静态网站生成器，它简洁易用，同时又强大灵活。通过这篇教程，你应该已经学会了如何使用 VuePress 搭建博客并部署到 GitHub Pages。

如果你想了解更多关于 VuePress 的知识，可以查看 VuePress 官方文档。

希望这篇教程对你有所帮助！如果你有任何问题，欢迎在评论区留言。

注： 本文使用 VuePress v2 版本，如果你使用的是 v1 版本，配置可能会有所不同。

教程
#GitHub #教程 #静态网站 #VuePress
VuePress 搭建静态博客及部署指南
https://blog.wtx132.com/2025/09/20/VuePress搭建静态博客及部署指南/
作者
wutongxue132
发布于
2025年9月20日
许可协议