01-部署该博客

约 1844 字大约 6 分钟

部署

2024-08-26

该教程引自https://segmentfault.com/a/1190000045016644#item-6

引言

对于一个程序员小白来说，拥有一个专属自己的博客网站是很酷炫的事情，接下来我就教大家如何用 VuePress+GitHub Pages 来打造你的自动化部署个人博客。

一、为什么选择 VuePress 和 GitHub Pages

VuePress：为开发者量身定制的静态站点生成器

VuePress 的核心优势在于：

Markdown 为中心：编写文章就像写文档一样简单直接，支持 Markdown 扩展，让你专注于内容创作。
Vue 驱动的主题系统：自定义主题或使用现成的主题，轻松打造个性化界面。
性能卓越：预渲染静态 HTML，加载速度快，SEO 友好。

GitHub Pages：免费且强大的托管服务

GitHub Pages 是 GitHub 提供的一项服务，允许用户免费托管静态网站。与 VuePress 结合，你可以：

自动化部署：每次推送代码到 GitHub 仓库，自动更新网站内容。
域名绑定：支持自定义域名，让你的博客更加专业。
安全稳定：依托 GitHub 的基础设施，无需担心服务器维护问题。

二、准备工作

github 账号。
依赖环境：Node.Js v20.10.0+。
包管理器：pnpm、yarn、npm，推荐使用 pnpm。

github 账号，访问 github 卡顿可使用Watt Toolkit (原名 Steam++)加速。
vuepress 官网 v2.0.0-rc.14 文档写的 v18.16.0+似乎不准确，使用 v18.17.0 运行会报错，需升级 nodejs。

三、创建 GitHub Pages 网站

在 github 中创建仓库，存储库必须命名为username.github.io，创建 README.md 文件。

依次点击 Settings→Pages→Visit site，打开访问已发布的网站。

现在你已经拥有一个属于自己的网站啦

四、使用 VuePress 初始化项目

方式一：命令行创建：

通过 create-vuepress 直接创建项目模板
项目类型改为 docs，回车键一直到最后启动项目，或手动运行命令pnpm run docs:dev启动项目。

pnpm create vuepress vuepress-starter

blog 和 docs 项目类型模板的区别？

blog (博客) 模板：适用于需要频繁更新内容、注重文章的展示和归档的场景。

博客文章的分页。
用于显示最近文章、分类和标签的侧边栏或首页。
文章的元数据支持，例如发表日期、作者信息等。
RSS/Atom Feed 支持，便于读者订阅更新。
可能会有评论系统集成或其他社交媒体分享功能的支持。

docs (文档) 模板：更适合技术文档、产品手册等需要结构化内容展示的场景。

以目录结构组织的内容。
自动从 Markdown 文件的标题生成导航菜单。
更加简洁的页面布局，专注于内容展示。
通常不包含博客相关的特性，如分页、文章元数据等。

方式二：手动创建：

mkdir vuepress-starter
cd vuepress-starter

初始化项目，生成 package.json 文件

pnpm init

安装 VuePress

# 安装 vuepress
pnpm install -D vuepress@next
# 安装 vue依赖
pnpm install -D vue
# 安装打包工具和主题
pnpm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next

⚠️ 缺失 vue 依赖会造成项目运行和部署失败，使用 pnpm 安装 vuepress 时偶尔会不安装 vue 依赖，可能与安装的 vuepress 版本有关。

创建docs目录和docs/.vuepress目录

mkdir docs
mkdir docs/.vuepress

创建 VuePress 配置文件docs/.vuepress/config.js

import { viteBundler } from "@vuepress/bundler-vite";
import { defaultTheme } from "@vuepress/theme-default";
import { defineUserConfig } from "vuepress";

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),
});

新建一篇文档 docs/README.md，输入文字# Hello VuePress

echo '# Hello VuePress' > docs/README.md # 不推荐此方式

创建完成后，你项目的目录结构应该是这样的：

├─ docs
│ ├─ .vuepress
│ │ └─ config.js
│ └─ README.md
└─ package.json

在 package.json 文件添加以下 scripts

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

启动服务器

pnpm run docs:dev

打开http://localhost:8080，查看运行效果

五、自动化部署配置

ℹ️ 这里我选择用同一个仓库的docs 分支用来放项目源代码，main 分支来存放打包部署后的静态文件。

git 初始化，并与建立远程仓库关联，以下 username 需换成自己的 github 用户名

git init
git checkout -b docs
git remote add origin https://github.com/username/username.github.io.git

添加.gitignore 文件

node_modules
# VuePress 默认临时文件目录
docs/.vuepress/.temp
# VuePress 默认缓存目录
docs/.vuepress/.cache
# VuePress 默认构建生成的静态文件目录
docs/.vuepress/dist

修改/添加.github/workflows/docs.yml工作流配置文件

name: 部署文档

on:
  push:
    branches:
      # 确保这是你正在使用的分支名称
      - docs

permissions:
  contents: write

jobs:
  deploy-main:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          # 如果你文档需要 Git 子模块，取消注释下一行
          # submodules: true

      - name: 安装 pnpm
        uses: pnpm/action-setup@v2
        with:
          run_install: true
          version: 8


      - name: 设置 Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: pnpm


      - name: 构建文档
        env:
          NODE_OPTIONS: --max_old_space_size=8192
        run: |-
          pnpm run docs:build
          > docs/.vuepress/dist/.nojekyll

      - name: 部署文档
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # 这是文档部署到的分支名称
          branch: main
          folder: docs/.vuepress/dist

使用命令行/代码编辑器推送代码，触发 GitHub Actions 自动部署

git add .
git commit -m "first commit"
git push --set-upstream origin docs

部署成功后，访问已发布的网站，网址为https://username.github.io

六、问题记录

使用 node-v18.17.0 安装依赖，运行项目报错'node:events' does not provide an export named 'addAbortListener'？解决方法：需升级 nodejs 版本，VuePress 官网文档 v2.0.0-rc.14 写的依赖 Node.js v18.16.0+似乎不准确；
使用 Steam++后，git 拉取推送代码报错 SSL 证书/443 Time out 问题？解决方法：见参考文档 3。
运行本地项目网页显示乱码问题？解决方法：用echo '# Hello VuePress' > docs/README.md创建的文件格式为 UTF-16LE，网页显示会产生乱码，需使用记事本将文件另存为所有文件保存类型UTF-8 编码格式；
使用 VuePress 官网文档.github/workflows/docs.yml代码配置工作流导致的部署问题？解决方法： a. 在 github 网址配置并生成 GITHUB_TOKEN 右上角账户 Settings→Developer settings→Personal access tokens→Tokens (classic)→Generate new token (classic)

b. 开启 Workflow 读写仓库权限修改配置 Settings→Actions→General→Workflow permissions，选择支持读写权限，点击 save 保存。

七、参考文档

八、结尾

至此，大功告成，你已经成功搭建了一个基于 VuePress+GitHub Pages 的个人博客。

更新日志

2026/5/5 18:19

查看所有更新日志

fde06-docs: 添加 doc 技术文档于 2026/5/5