共计 6963 个字符，预计需要花费 18 分钟才能阅读完成。
什么是 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 有很多不兼容的地方，也踩了很多坑，记录一下。
安装 VuePress
最好有自己的域名，星哥这里使用的是 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"
}
}
运行 docs:dev 脚本可以启动开发服务器:
yarn docs:devVuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。
报错：
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/
构建你的网站
运行 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有两个分支
3. 设置域名访问
自有域名 vuepress-v2.xgss.net 解析到 github 中
Settings –> Pages
把 vuepress-v2.xgss.net CNAME 解析到 funet8.github.io
把 你的域名 解析到 < 你的 github 账号名 >.github.io
等待解析生效，github 会提示 DNS check successful
勾选 Enforce HTTPS，强制
直接根据官方文档先初始化项目就行了，注意文档的版本，v1 和 v2 还是有很多地方不同的。
4. 用 GitHub Actions 部署到 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
报错没有配置 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"
解决
在 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
解决
安装 pnpm
$ npm install -g pnpm
added 1 package in 3s
$ pnpm -v
10.11.1
$rm -rf node_modules/
$ pnpm installpnpm 包管理的问题
由于官方的教程 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 权限（即推送权限）。
如图，勾选：Read and write permissions
保存。
6. 提交成功
但是当我访问页面的时候
https://funet8.github.io/vuepress-v2.xgss.net/无尽的 404 让人头疼
再次修改
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，同时还配置了自己的个人域名。这不仅为你提供了一个高效的知识管理平台，还能让你更好地记录学习过程并分享给他人。希望这篇教程对你有所帮助，祝你搭建博客愉快！
