使用VuePress2.X构建个人知识博客，并且用个人域名部署到GitHub Pages中

news2025/6/8 11:59:23

使用VuePress2.X构建个人知识博客，并且用个人域名部署到GitHub Pages中

什么是VuePress

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown 来书写内容（如文档、博客等），然后 VuePress 会帮助你生成一个静态网站来展示它们。VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求，但是现在它已经在帮助大量用户构建他们的文档、博客和其他静态网站。官网：

https://vuepress.vuejs.org/zh/

VuePress1.X和VuePress2.X区别

最开始星哥使用的是VuePress1.X（https://vuepress.xgss.net/），后期由于nodejs升级了导致VuePress1.X使用不了，一直报错。

无奈升级到VuePress2.X，2.x和1.x有很多不兼容的地方，也踩了很多坑，记录一下。

image-20250606145334981

安装VuePress

环境： window10

最好有自己的域名，星哥这里使用的事vuepress-v2.xgss.net

软件安装：nodejs和git

由于官方的教程docs.yml文件是pnpm作为包管理器，本人最开始使用的是yarn导致GitHub Actions失败，所以使用pnpm重新安装VuePress

星哥最开始使用的yarn，后来改成了pnpm，所以这个笔记遇到yarn一律改成pnpm既可。

https://vuepress.vuejs.org/zh/guide/deployment.html#github-pages

重新安装VuePress

安装
$ npm install -g pnpm
added 1 package in 3s
$ pnpm -v
10.11.1

pnpm create vuepress vuepress-starter
mkdir vuepress-starter
cd vuepress-starter

安装vuepress
pnpm init
pnpm add -D vuepress@next vue
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

安装调试插件
pnpm add -D sass-embedded
安装搜索插件
pnpm add -D @vuepress/plugin-search@next

启动开发服务器
pnpm docs:dev

构建网站：
pnpm docs:build

以下是使用yarn安装，这里推荐使用pnpm安装

你可以通过 create-vuepress 直接创建项目模板。
yarn create vuepress vuepress-starter

创建并进入一个新目录
mkdir vuepress-starter
cd vuepress-starter

初始化项目
git init
yarn init

# 安装 vuepress
yarn add -D vuepress@next
# 安装打包工具和主题
yarn add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

创建 VuePress 配置文件

docs/.vuepress/config.js

mkdir -p docs/.vuepress/
vi 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(),
})

创建你的第一篇文档

echo '# Hello VuePress' > docs/README.md

启动开发服务器

你可以在 package.json 中添加一些 scripts ：

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

image-20250605102058056

运行 docs:dev 脚本可以启动开发服务器:

yarn docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。

报错：

image-20250605102257832

yarn add -D sass-embedded

再启动开发服务器

$ yarn docs:dev
yarn run v1.22.22
$ vuepress dev docs
√ Initializing and preparing data - done in 58ms
10:22:16 [vite] (client) Re-optimizing dependencies because lockfile has changed

  vite v6.3.5 dev server running at:

  ➜  Local:   http://localhost:8080/
  ➜  Network: http://192.168.1.251:8080/
  ➜  Network: http://192.168.52.1:8080/
  ➜  Network: http://192.168.152.1:8080/

使用浏览器访问http://localhost:8080/

image-20250605102401921

构建你的网站

运行 docs:build 脚本可以构建你的网站：

yarn docs:build

查看vuepress版本

yarn list vuepress

vuepress主题（报错）

更换主题，一直报错就决定不换主题了，使用默认主题了！

官网： https://marketplace.vuejs.press/zh/themes/

VuePress Theme Mix

https://vuepress-theme-mix.netlify.app/zh/guide/getting-started.html

安装VuePress Theme Mix

yarn add -D vuepress-theme-mix@next

使用与配置

import { defineUserConfig } from 'vuepress'
import mixTheme from 'vuepress-theme-mix'

export default defineUserConfig({
  // ...

  theme: mixTheme({
    // 在这里配置主题
  }),

  // ...
})

VuePress配置搜索

安装插件

首先，在你的 VuePress 项目中安装该插件：
pnpm add -D @vuepress/plugin-search@next
# 或者
yarn add -D @vuepress/plugin-search@next
# 或者
npm i -D @vuepress/plugin-search@next

配置config.js

.vuepress/config.js 示例:
import { searchPlugin } from '@vuepress/plugin-search'

module.exports = {
  plugins: [
    searchPlugin({
      // 插件选项
      // 可以配置的选项包括：
      // maxSuggestions: 5, // 最多显示多少条搜索结果
      // isSearchable: (page) => page.path !== '/', // 排除特定页面
      // hotKeys: ['s', '/'], // 激活搜索框的快捷键
      // locales: { // 多语言支持
      //   '/': {
      //     placeholder: '搜索',
      //   },
      //   '/en/': {
      //     placeholder: 'Search',
      //   },
      // },
      // get.Display.Text: (page) => { /* 自定义搜索结果显示文本 */ },
      // search: (query, pages) => { /* 自定义搜索逻辑 */ },
    }),
  ],
}

报错1

使用

yarn docs:build

报错，由于图片没有上传到oss中导致报错。

error [vite:asset] Could not load G:/STAR学习/vuepress-starter/docs/./chatgpt/H:/typora_images/image-20240415180831846.png (imported by docs/.vuepress/.temp/pages/chatgpt/15.免费使用GPT-4的3种方法，白嫖大模型.html.vue): ENOENT: no such file or directory, open 'G:\STAR学习\vuepress
-starter\docs\chatgpt\H:\typora_images\image-20240415180831846.png'

解决：

grep -R 'typora_images' ./*| grep -v '.vuepress/'
查看所有未上传的图片

把所有的图片上传到oss中，再生成yarn docs:build

配置到GitHub Pages

前置条件，需要你有自己的域名，如果没有自有的域名，也可以使用github的域名，但是国内可能访问不畅。

自己的域名CNAME到 https://<USERNAME>.github.io

或者使用官方域名： https://<USERNAME>.github.io/<REPO>/

这里星哥使用vuepress-v2.xgss.net 解析到 funet8.github.io

1.github新建仓库

新建git 仓库
vuepress-v2.xgss.net

克隆到本地
git clone git@github.com:funet8/vuepress-v2.xgss.net.git
把docs的文档拷贝进去

2.执行

#提交到github仓库-vuepress-v2分支
#git init
git add -A
git commit -m 'deploy.sh-vuepressV2脚本自动提交'
git push -f git@github.com:funet8/vuepress-v2.xgss.net.git main

有两个分支

image-20250605161934191

3.设置域名访问

自有域名 vuepress-v2.xgss.net 解析到github中

Settings --> Pages

image-20250605162124719

把 vuepress-v2.xgss.net CNAME解析到 funet8.github.io
把 你的域名  解析到 <你的github账号名>.github.io

image-20250605162742075

等待解析生效，github会提示DNS check successful

勾选 Enforce HTTPS，强制

直接根据官方文档先初始化项目就行了，注意文档的版本，v1和v2还是有很多地方不同的。

4.用 GitHub Actions 部署到 GitHub Pages

参考：https://vuepress.vuejs.org/zh/guide/deployment.html#github-pages

创建 .github/workflows/docs.yml 文件来配置工作流。

name: docs

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: 设置 pnpm
        uses: pnpm/action-setup@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          # 选择要使用的 node 版本
          node-version: 22
          # 缓存 pnpm 依赖
          cache: pnpm

      - name: 安装依赖
        run: pnpm install --frozen-lockfile

      # 运行构建脚本
      - name: 构建 VuePress 站点
        run: pnpm docs:build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: 部署到 GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          # 部署到 gh-pages 分支
          target_branch: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          build_dir: docs/.vuepress/dist
        env:
          # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

提交代码，触发Actions

image-20250605165314078

报错没有配置packageManager

Error: No pnpm version is specified. Please specify it by one of the following ways: - in the GitHub Action config with the key "version" - in the package.json with the key "packageManager"

image-20250605165722852

解决

在 package.json添加

"packageManager": "pnpm@10.11.1"

或者在 .github/workflows/docs.yml 文档中添加
      - name: 设置 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: '8.x'

报错无pnpm-lock.yaml

Dependencies lock file is not found in /home/runner/work/vuepress-v2.xgss.net/vuepress-v2.xgss.net. Supported file patterns: pnpm-lock.yaml

image-20250605171442396

解决

安装pnpm

$ npm install -g pnpm
added 1 package in 3s


$ pnpm -v
10.11.1

$rm -rf node_modules/

$ pnpm install

pnpm包管理的问题

由于官方的教程docs.yml文件是pnpm作为包管理器，本人最开始使用的是yarn导致GitHub Actions失败，所以重新安装VuePress

https://vuepress.vuejs.org/zh/guide/deployment.html#github-pages

重新安装VuePress

mv package.json package-yarn.json
rm -rf node_modules

安装vuepress
pnpm init
pnpm add -D vuepress@next vue
pnpm add -D @vuepress/bundler-vite@next @vuepress/theme-default@next

调试插件
pnpm add -D sass-embedded
搜索插件
pnpm add -D @vuepress/plugin-search@next

启动开发服务器
pnpm docs:dev

构建网站：
pnpm docs:build

5.工作流权限

在仓库的 Settings > Actions > General，确保 GITHUB_TOKEN 的权限被设置为 write 权限（即推送权限）。

image-20250605183211238

如图，勾选：Read and write permissions

保存。

6.提交成功

image-20250606094256875

但是当我访问页面的时候

https://funet8.github.io/vuepress-v2.xgss.net/

无尽的404让人头疼

image-20250606094350107

再次修改

docs\.vuepress\config.js
里面的配置
base: '/vuepress-v2.xgss.net/', // 部署到github相关的配置 
则是使用https://funet8.github.io/vuepress-v2.xgss.net/ 访问

改成使用域名，发现缺少CNAME 文件

于是在docs.yml文件中添加一步

      - name: Add CNAME file # 添加 CNAME 文件
        run: echo 'vuepress-v2.xgss.net' > docs/.vuepress/dist/CNAME

最终使用域名 vuepress-v2.xgss.net 可以访问博客页面了。

最后

写文不易，如果你都看到了这里，请点个赞和在看，分享给更多的朋友；也别忘了关注星哥玩云！这里有满满的干货分享，还有轻松有趣的技术交流～点个赞、分享给身边的小伙伴，一起成长，一起玩转技术世界吧！ 😊

通过以上步骤，你成功地使用VuePress 2.X搭建了一个个人知识博客，并将其部署到GitHub Pages，同时还配置了自己的个人域名。这不仅为你提供了一个高效的知识管理平台，还能让你更好地记录学习过程并分享给他人。希望这篇教程对你有所帮助，祝你搭建博客愉快！

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/2404100.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

手写Promise.all

手写Promise.all

前言 之前在看远方os大佬直播的时候看到有让手写的Promise.all的问题&#xff0c;然后心血来潮自己准备手写一个 开始 首先&#xff0c;我们需要明确原本js提供的Promise.all的特性 Promise.all返回的是一个Promise如果传入的数据中有一个reject即整个all返回的就是reject&…
阅读更多...
2025年6月|注意力机制|面向精度与推理速度提升的YOLOv8模型结构优化研究：融合ACmix的自研改进方案

2025年6月|注意力机制|面向精度与推理速度提升的YOLOv8模型结构优化研究：融合ACmix的自研改进方案

版本&#xff1a; 8.3.143(Ultralytics YOLOv8框架) ACmix模块原理 在目标检测任务中&#xff0c;小目标&#xff08;如裂缝、瑕疵、零件边缘等&#xff09;由于其尺寸较小、纹理信息稀疏&#xff0c;通常更容易受到图像中复杂背景或噪声的干扰&#xff0c;从而导致漏检或误检…
阅读更多...
利用qcustomplot绘制曲线图

利用qcustomplot绘制曲线图

本文详细介绍了qcustomplot绘制曲线图的流程&#xff0c;一段代码一段代码运行看效果。通过阅读本文&#xff0c;读者可以了解到每一项怎么用代码进行配置&#xff0c;进而实现自己想要的图表效果。&#xff08;本文只针对曲线图&#xff09; 1 最简单的图形&#xff08;入门&…
阅读更多...
【基础算法】枚举（普通枚举、二进制枚举）

【基础算法】枚举（普通枚举、二进制枚举）

文章目录 一、普通枚举1. 铺地毯(1) 解题思路(2) 代码实现 2. 回文日期(1) 解题思路思路一&#xff1a;暴力枚举思路二&#xff1a;枚举年份思路三&#xff1a;枚举月日 (2) 代码实现 3. 扫雷(2) 解题思路(2) 代码实现 二、二进制枚举1. 子集(1) 解题思路(2) 代码实现 2. 费解的…
阅读更多...
智能对联网页小程序的仓颉之旅

智能对联网页小程序的仓颉之旅

#传统楹联遇上AI智能体&#xff1a;我的Cangjie Magic开发纪实 引言&#xff1a;一场跨越千年的数字对话 "云对雨&#xff0c;雪对风&#xff0c;晚照对晴空"。昨天晚上星空璀璨&#xff0c;当我用仓颉语言写下第一个智能对联网页小程序的Agent DSL代码时&#xff0…
阅读更多...
Python分形几何可视化—— 复数迭代、L系统与生物分形模拟

Python分形几何可视化—— 复数迭代、L系统与生物分形模拟

Python分形几何可视化—— 复数迭代、L系统与生物分形模拟 本节将深入探索分形几何的奇妙世界&#xff0c;实现Mandelbrot集生成器和L系统分形树工具&#xff0c;并通过肺部血管分形案例展示分形在医学领域的应用。我们将使用Python的NumPy进行高效计算&#xff0c;结合Matplo…
阅读更多...
【超详细】英伟达Jetson Orin NX-YOLOv8配置与TensorRT测试

【超详细】英伟达Jetson Orin NX-YOLOv8配置与TensorRT测试

文章主要内容如下&#xff1a; 1、基础运行环境配置 2、Torch-GPU安装 3、ultralytics环境配置 4、Onnx及TensorRT导出详解 5、YOLOv8推理耗时分析 基础库版本&#xff1a;jetpack5.1.3, torch-gpu2.1.0, torchvision0.16.0, ultralytics8.3.146 设备的软件开发包基础信息 需…
阅读更多...
Go语言学习--＞项目中引用第三方库方式

Go语言学习--＞项目中引用第三方库方式

Go语言学习–&#xff1e;项目中引用第三方库方式 1 执行 go mod tidy 分析引入的依赖有没有正常放在go.mod里面 找到依赖的包会自动下载到本地 并添加在go.mod里面 执行结果&#xff1a; 2 执行go get XXXX&#xff08;库的名字&#xff09;
阅读更多...
每日Prompt：云朵猫

每日Prompt：云朵猫

提示词 仰视&#xff0c;城镇的天空&#xff0c;一片形似猫咪的云朵&#xff0c;用黑色的简笔画&#xff0c;勾勒出猫咪的形状&#xff0c;可爱&#xff0c;俏皮&#xff0c;极简
阅读更多...
AI浪潮下的IT行业：威胁、转变与共生之道

AI浪潮下的IT行业：威胁、转变与共生之道

目录 前言1 AI在IT行业的具体应用场景1.1 软件开发中的AI助手1.2 运维与监控的智能化1.3 测试自动化与质量保障1.4 安全防护中的智能威胁识别 2 AI对IT从业者的实际影响2.1 工作内容的结构性变化2.2 技能结构的再平衡 3 IT从业者不可替代的能力与价值3.1 复杂系统的架构与抽象能…
阅读更多...
基于功能基团的3D分子生成扩散模型 - D3FG 评测

基于功能基团的3D分子生成扩散模型 - D3FG 评测

D3FG 是一个在口袋中基于功能团的3D分子生成扩散模型。与通常分子生成模型直接生成分子坐标和原子类型不同&#xff0c;D3FG 将分子分解为两类组成部分&#xff1a;官能团和连接体&#xff0c;然后使用扩散生成模型学习这些组成部分的类型和几何分布。 一、背景介绍 D3FG 来源…
阅读更多...
蓝耘服务器与DeepSeek的结合：引领智能化时代的新突破

蓝耘服务器与DeepSeek的结合：引领智能化时代的新突破

&#x1f31f; 嗨&#xff0c;我是Lethehong&#xff01;&#x1f31f; &#x1f30d; 立志在坚不欲说&#xff0c;成功在久不在速&#x1f30d; &#x1f680; 欢迎关注&#xff1a;&#x1f44d;点赞⬆️留言收藏&#x1f680; &#x1f340;欢迎使用&#xff1a;小智初学…
阅读更多...
无人机光纤FC接口模块技术分析

无人机光纤FC接口模块技术分析

运行方式 1. 信号转换&#xff1a;在遥控器端&#xff0c;模块接收来自遥控器主控板的电信号。 2.电光转换&#xff1a;模块内部的激光发射器将电信号转换成特定波长的光信号。 3.光纤传输&#xff1a;光信号通过光纤跳线传输。光纤利用全内反射原理将光信号约束在纤芯内进行…
阅读更多...
作为过来人，浅谈一下高考、考研、读博

作为过来人，浅谈一下高考、考研、读博

写在前面 由于本人正在读博&#xff0c;标题中的三个阶段都经历过或正在经历&#xff0c;本意是闲聊&#xff0c;也算是给将要经历的读者们做个参考、排雷。本文写于2022年&#xff0c;时效性略有落后&#xff0c;不过逻辑上还是值得大家参考&#xff0c;若所述存在偏颇&#…
阅读更多...
立志成为一名优秀测试开发工程师(第十一天)—Postman动态参数/变量、文件上传、断言策略、批量执行及CSV/JSON数据驱动测试

立志成为一名优秀测试开发工程师(第十一天)—Postman动态参数/变量、文件上传、断言策略、批量执行及CSV/JSON数据驱动测试

目录 一、Postman接口关联与正则表达式应用 1.正则表达式解析 2.提取鉴权码。 二、Postman内置动态参数以及自定义动态参数 1.常见内置动态参数&#xff1a; 2.自定义动态参数&#xff1a; 3.“编辑”接口练习 三、图片上传 1.文件的上传 2.上传后内容的验证 四、po…
阅读更多...
算法练习-回溯

算法练习-回溯

今天开始新的章节&#xff0c;关于算法中回溯法的练习&#xff0c;这部分题目的难度还是比较大的&#xff0c;但是十分锻炼人的思维与思考能力。 处理这类题目首先要注意几个基本点&#xff1a; 1.关于递归出口的设置&#xff0c;这是十分关键的&#xff0c;要避免死循环的产…
阅读更多...
一文带你入门Java Stream流，太强了，mysqldba面试题及答案

一文带你入门Java Stream流，太强了，mysqldba面试题及答案

list.add(“世界加油”); list.add(“世界加油”); long count list.stream().distinct().count(); System.out.println(count); distinct() 方法是一个中间操作&#xff08;去重&#xff09;&#xff0c;它会返回一个新的流&#xff08;没有共同元素&#xff09;。 Stre…
阅读更多...
FastAPI安全异常处理：从401到422的奇妙冒险

FastAPI安全异常处理：从401到422的奇妙冒险

title: FastAPI安全异常处理：从401到422的奇妙冒险 date: 2025/06/05 21:06:31 updated: 2025/06/05 21:06:31 author: cmdragon excerpt: FastAPI安全异常处理核心原理与实践包括认证失败的标准HTTP响应规范、令牌异常的特殊场景处理以及完整示例代码。HTTP状态码选择原则…
阅读更多...
阿里云 RDS mysql 5.7 怎么 添加白名单 并链接数据库

阿里云 RDS mysql 5.7 怎么 添加白名单 并链接数据库

阿里云 RDS mysql 5.7 怎么 添加白名单 并链接数据库 最近帮朋友 完成一些运维工作 &#xff0c;这里记录一下。 文章目录 阿里云 RDS mysql 5.7 怎么 添加白名单 并链接数据库最近帮朋友 完成一些运维工作 &#xff0c;这里记录一下。 阿里云 RDS MySQL 5.7 添加白名单1. 登录…
阅读更多...
《Brief Bioinform》: 鼠脑单细胞与Stereo-seq数据整合算法评估

《Brief Bioinform》: 鼠脑单细胞与Stereo-seq数据整合算法评估

一、写在前面 基因捕获效率、分辨率一直是空间转录组细胞类型识别的拦路虎&#xff0c;许多算法能够整合单细胞(single-cell, sc)或单细胞核(single-nuclear, sn)数据与空间转录组数据&#xff0c;从而帮助空转数据的细胞类型注释。此前我们介绍过近年新出炉的Stereo-seq平台&…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023