🚀從零到一，用VuePress+GitHub Pages打造你的自動化部署個人博客！詳情 - vuepress,github-pages,github-actions Ajianxian 博客

引言

對於一個程序員小白來説，擁有一個專屬自己的博客網站是很酷炫的事情，接下來我就教大家如何用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 站點 - GitHub 文檔
使用Steam++解決github的 443：Timed out問題 · BeyondDimension/SteamTools · Discussion #234

八、結尾

至此，大功告成，你已經成功搭建了一個基於VuePress+GitHub Pages的個人博客。

Ajianxian 博客

Ajianxian 博客

博客 / 詳情