当前位置：首页 > news >正文

VuePress-theme-hope 搭建个人博客 2【快速上手】 —— 安装、部署防止踩坑篇

news 2025/9/13 11:19:57

续👆VuePress、VuePress-theme-hope 搭建个人博客 1【快速上手】

项目常用命令

vuepress dev [dir] 会启动一个开发服务器，以便让你在本地开发你的 VuePress 站点。
vuepress build [dir] 会将你的 VuePress 站点构建成静态文件，以便你进行后续部署。

使用模板

如果使用 VuePress Theme Hope 模板，可以在 package.json 中发现下列三个命令:

{"scripts": {"docs:build": "vuepress build src","docs:clean-dev": "vuepress dev src --clean-cache","docs:dev": "vuepress dev src"}
}

可以使用:

npm docs:dev 启动开发服务器
npm docs:build 构建项目并输出
npm docs:clean-dev 清除缓存并启动开发服务器

终止开发服务器

如果你需要终止开发服务器，请点击终端，并连续两次按下 Ctrl + C。

页面的生成

VuePress 是以 Markdown 为中心的。你项目中的每一个 Markdown 文件都是一个单独的页面。

默认情况下，页面的路由路径是根据你的 Markdown 文件的相对路径决定的。

由于你的项目是通过创建助手生成的，那么你会得到以下文件结构:

└─ src├─ guide│  ├─ ...│  └─ page.md│  └─ markdown.md│  └─ README.md├─ ...├─ slide.md└─ README.md

你的 Markdown 文件对应的路由路径为:

相对路径	路由路径
`/README.md`	`/`
`/slide.md`	`/slide.html`
`/guide/README.md`	`/guide/`
`/guide/slide.md`	`/guide/slide.html`
`/guide/page.md`	`/guide/page.html`

README.md是特例，在 Markdown 中，它会作为所在文件夹的主页。所以在渲染为网页时，它的对应路径为网页中的主页路径 index.html。

VuePress 项目结构

VuePress 只控制 VuePress 项目文件夹中的文件，也就是默认模板生成的 src 文件夹，项目下的其他文件不受 VuePress 控制。

一个基本的项目结构如下:

.
├── .github (可选的) → GitHub 配置文件存放路径
│    └── workflow → GitHub 工作流配置
│         └── docs-deploy.yml → 自动部署文档的工作流
│
├── src → 文档文件夹
│    │
│    ├── .vuepress (可选的) → VuePress 配置文件夹
│    │    │
│    │    ├── dist (默认的) → 构建输出目录
│    │    │
│    │    ├── public (可选的) → 静态资源目录
│    │    │
│    │    ├── styles (可选的) → 用于存放样式相关的文件
│    │    │
│    │    ├── config.{js,ts} (可选的) → 配置文件的入口文件
│    │    │
│    │    └── client.{js,ts} (可选的) → 客户端文件
│    │
│    ├── ... → 其他项目文档
│    │
│    └── README.md → 项目主页
│
└── package.json → Nodejs 配置文件

部署构建项目

当你在本地完成项目的初步开发后，你就可以使用 pnpm docs:build 命令构建网站。
如果你在使用模板，网站内容将会输出到 VuePress 项目的 .vuepress/dist 文件夹下。这些文件就是 VuePress 的最终输出结果。
你可以将此文件夹的内容部署到你网站的服务器上。最简单的做法是上传到 GitHub 并开启 GitHub Pages。

部署到 GitHub Pages

如果你在使用模板，且在创建过程中选择了创建自动部署文档的 GitHub 工作流，那么你唯一要做的就是设置正确的 base选项

如果你准备发布到 https://<USERNAME>.github.io/，你必须将整个项目上传至 https://github.com/<USERNAME>/<USERNAME>.github.io 仓库。在这种情况下你无需进行任何更改，因为 base 默认就是 "/"。
如果你的仓库地址是一个普通的形如 https://github.com/<USERNAME>/<REPO> 的格式，网站将会被发布到 https://<USERNAME>.github.io/<REPO>/ ，也就是说，你需要将 base 设置为 "/<REPO>/"。
当操作完成后，你应该前往 GitHub 仓库的设置页面，选择 gh-pages 作为 GitHub Pages 的源。