跳至主要內容

部署个人博客

shuashua2025/10/10大约 7 分钟博客搭建VuePress

环境准备：搭建本地开发环境

技术选型：

锁定VuePress 2.x + VuePress-Hope-Theme

VuePress-Hope-Theme 官方教程

安装Node.js

  • 访问Node.js 官网，下载 LTS 版本（推荐 16.x 及以上，需与 VuePress 2.x 兼容）；

  • 安装完成后，打开终端执行node -v和npm -v，确认版本正常（如v18.17.0和v9.6.7）。

框架搭建：初始化 VuePress-Hope 项目

初始化

参照官方教程的快速上手即可，写得很清楚：

创建项目 | vuepress-theme-hope

F:\my_blog>npm init vuepress-theme-hope@latest shua_blog
Need to install the following packages:
create-vuepress-theme-hope@2.0.0-rc.94
Ok to proceed? (y) y


> npx
> create-vuepress-theme-hope shua_blog

√ Select a language to display / 选择显示语言 简体中文
√ 选择包管理器 npm
√ 你想要使用哪个打包器？ vite
生成 package.json...
√ 设置应用名称 shua-blog
√ 设置应用描述 A project of vuepress-theme-hope
√ 设置应用版本号 2.0.0
√ 设置协议 MIT
生成 tsconfig.json...
√ 你想要创建什么类型的项目？ blog
√ 项目需要用到多语言么? No
生成模板...
√ 是否初始化 Git 仓库? Yes
√ 是否需要一个自动部署文档到 GitHub Pages 的工作流？ Yes
√ 选择你想使用的源 国内镜像源
安装依赖...
这可能需要数分钟，请耐心等待.
我们无法正确输出子进程的进度条，所以进程可能会看似未响应

added 399 packages in 50s

112 packages are looking for funding
  run `npm fund` for details
模板已成功生成!
√ 是否想要现在启动 Demo 查看? Yes
启动开发服务器...
启动成功后，请在浏览器输入给出的开发服务器地址(默认为 'localhost:8080')

> shua-blog@2.0.0 docs:dev
> vuepress-vite dev src

√ Initializing and preparing data - done in 743ms

  vite v7.0.7 dev server running at:

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://169.254.133.40:8080/
  ➜  Network: http://192.168.19.1:8080/
  ➜  Network: http://192.168.217.1:8080/
  ➜  Network: http://10.79.62.167:8080/

项目命令

最常用：npm run docs:dev（本地开发）

  • 效果：执行后终端会显示 Local: http://localhost:8080/，打开浏览器访问这个地址，就能看到博客的实时效果 —— 你修改 src 目录下的文章（如 src/posts 里的 Markdown 文件）、配置（如 src/.vuepress/config.ts）后，浏览器会自动刷新，无需手动重启服务器。

部署前必用：npm run docs:build（构建静态文件）

  • 输出位置：构建完成后，所有静态文件（HTML、CSS、JS、图片等）会存放在 shua_blog/dist 文件夹中 —— 后续部署时，只需要把 dist 文件夹里的内容上传到服务器（如 GitHub Pages、Netlify 等）即可。
  • 注意：构建前确保本地预览没有报错（比如链接失效、语法错误），否则构建会失败，终端会提示具体错误位置（如某篇 Markdown 语法错误），修复后再重新执行构建命令。

排障专用：npm run docs:clean-dev（清除缓存）

  • 适用场景

    ：遇到以下情况时用这个命令：

    • 修改了配置文件（如 config.ts），但本地预览没变化；
    • 更换了主题样式，却残留旧样式；
    • 终端提示 “缓存冲突”“临时文件错误” 等信息。

  • 原理：VuePress 会缓存部分资源来加快开发速度，但有时缓存会导致更新不生效，这个命令会清除缓存和临时文件，让服务器以 “干净状态” 启动。

部署到GitHub Pages

一、创建 GitHub 仓库

首先需要在 GitHub 上创建一个仓库，仓库类型决定后续的路径配置，分两种情况：

  1. 情况 1：部署到「用户名专属域名」（推荐，如 https://你的用户名.github.io）

    • 仓库名称必须是 <你的GitHub用户名>.github.io（比如你用户名叫 shua，仓库名就叫 shua.github.io）。

    • 这个仓库的特殊之处：部署后可直接通过 https://shua.github.io 访问，无需额外路径。

  2. 情况 2：部署到「普通仓库子路径」（如 https://你的用户名.github.io/我的博客/）

二、核心配置：修改 base 路径

base 是 VuePress 项目的「基础路径」，必须和 GitHub 仓库的访问路径匹配，否则部署后会出现「样式错乱、资源加载失败」。

  1. 打开项目中的 src/.vuepress/config.ts

  2. 根据仓库类型配置 base

base 保持默认的 / 即可，无需修改，配置如下：

export default defineUserConfig({
  base: "/", // 无需改，因为访问路径是根域名
  lang: "zh-CN",
  title: "你的博客名",
  // 其他配置...
});
  • 如果是情况 2（普通仓库，如 my-blog**）**：

base 必须设置为 /仓库名/（结尾的 / 不能少），比如仓库名是 my-blog，配置如下：

export default defineUserConfig({
  base: "/my-blog/", // 关键：替换成你的仓库名
  lang: "zh-CN",
  title: "你的博客名",
  // 其他配置...
});

三、部署操作：两种方式（自动部署优先，模板自带）

方式 1：自动部署（推荐，模板自带工作流）

模板会自动生成「GitHub Actions 工作流文件」（路径：项目根目录/.github/workflows/deploy.yml），只要把代码推到 GitHub，工作流会自动帮你构建项目、生成 gh-pages 分支（部署用的分支）。

步骤：

  1. 提交本地代码到 GitHub

打开终端，在你的 shua_blog 项目根目录执行以下命令（替换成你的仓库地址）：

# 初始化Git（如果之前没初始化，项目创建时选了Git则跳过）
git init
# 关联GitHub仓库（替换成你的仓库URL）
git remote add origin https://github.com/你的用户名/你的仓库名.git
# 添加所有文件
git add .
# 提交代码（备注信息）
git commit -m "初始化博客，准备部署"
# 推到GitHub的main分支（或master分支，看你仓库默认分支）
git push -u origin main
  1. 等待工作流运行完成

打开你的 GitHub 仓库页面 → 点击顶部「Actions」→ 能看到一个正在运行的工作流（比如叫 Deploy），等待它变成绿色的「Success」。

工作流完成后，会自动创建一个名为 gh-pages 的分支（这个分支里存的是构建后的静态文件）。

  1. 设置 GitHub Pages 源

进入仓库的「Settings」（设置）→ 往下滑找到「Pages」选项 → 在「Source」（源）下拉框中，选择「Deploy from a branch」→ 「Branch」（分支）选择 gh-pages，「Folder」（文件夹）保持 /(root) → 点击「Save」保存。

方式 2：手动部署（没选自动工作流时用）

如果创建项目时没选自动工作流，需要手动把构建后的 dist 文件夹推到 gh-pages 分支。

步骤：

  1. 构建项目

在 shua_blog 根目录执行命令，生成静态文件（输出到 dist 文件夹）：

npm run docs:build
  1. 安装 gh-pages 工具（用于推送 dist 到 gh-pages 分支）
npm install -D gh-pages
  1. 配置 package.json 脚本

打开 package.json，在 scripts 里加一个部署脚本：

{
  "scripts": {
    "docs:dev": "vuepress dev src",
    "docs:build": "vuepress build src",
    "deploy": "gh-pages -d dist" // 新增的部署脚本：把dist文件夹推到gh-pages分支
  }
}
  1. 执行部署命令
npm run deploy
  1. 设置 GitHub Pages 源

和自动部署的步骤 3 一样：仓库「Settings」→「Pages」→ 选择 gh-pages 分支 → 保存。

四、验证部署结果

设置完成后，GitHub 会显示「Your site is live at https://xxx.github.io/xxx/」，点击这个链接就能访问你的博客了。

注意：GitHub Pages 生效可能需要 1-5 分钟，若刚开始访问是 404，稍等几分钟再刷新。

域名映射

配置 DNS 解析

  1. 注册域名
  2. 添加 CNAME 记录

GitHub 仓库设置

  1. 添加自定义域名
    • 进入仓库 Settings > Pages，在 Custom domain 中输入你的域名（如 shuashua.site），点击 Save。
    • GitHub 会自动在仓库根目录创建或更新 CNAME 文件，内容为你的域名。
  2. 验证域名所有权
    • 若提示域名已被占用，需在 Settings > Pages 中点击 Verify ownership，按提示在 DNS 中添加 TXT 记录（如 _github-pages-verification-code.shuashua.site），验证通过后即可绑定。
默认页脚
Copyright © 2025 shuashua