最近有空整理旧文，于是用 vuepress-theme-hope 搭了一个个人技术站点，效果先睹为快：
博客首页看起来还不错吧？站点支持两个地址访问，后面会说明两种不同的部署方式：
GitHub Pages：https://trunks2008.github.io/
个人服务器：http://123.249.45.169:8080/
至于个人服务器为啥没用域名……看了ICP备案那一大堆材料和流程，我选择直接放弃。
下面记录一下使用 vuepress-theme-hope 搭建网站的完整流程以及我踩过的一些坑，如果你也有兴趣搭建自己的博客或文档站，可以跟着步骤操作。
准备工作
安装 Node.js
首先需要安装 Node.js，直接从官网下载即可。vuepress-theme-hope 支持 Node.js 16 的某些版本以及 18 以上的版本，为了保险起见，建议直接安装最新的 18 或更高版本：
https://nodejs.org/zh-cn/download
安装过程很简单，一路点击下一步。完成后在命令行输入 node -v 查看版本，能正常显示就说明安装成功了。
创建项目
创建一个新目录，在命令行中执行以下命令：
yarn create vuepress-theme-hope [dir]
这里的 [dir] 是一个参数，需要替换成你实际的项目目录名。命令执行过程中会有一些交互选项：
其中比较重要的选项是项目的 类型，可以选择博客（blog）和文档（docs）两种，生成的页面风格差异较大，我选择的是 docs 类型。
另外，如果你后续计划将网站部署到 GitHub Pages 上，在询问是否创建 GitHub Actions 工作流 时，记得选择 Yes。
安装完成后，可以选择立即启动 Demo 查看效果。在浏览器访问 http://localhost:8080，可以看到默认的文档类型首页：
如果当初选择的是 blog 类型，效果则是这样的：
当然，你也可以选择先不运行，之后在任何时候使用以下命令启动开发服务器：
yarn run docs:dev
项目骨架搭建好后，就可以开始定制内容了。先来看一下官方文档中关于 docs 项目文件结构的说明：
整体使用下来的感受是，vuepress-theme-hope 基本上不需要我们手写太多前端代码，核心工作就两件：
- 使用
Markdown 文档来管理和撰写页面内容。
- 使用
TypeScript 或 JavaScript 配置文件进行站点的基本配置。
了解项目结构后，我们分模块进行内容修改。
主页配置
项目的主页由 src 目录下的 README.md 文件进行配置。这个文件采用 Frontmatter 格式来定义页面的元数据和布局。
这里可以配置网站的名称（heroText）、标语（tagline）、Logo（heroImage）等。actions 数组用于添加页面上的操作按钮，features 数组则对应主页上展示的一个个功能模块卡片。
顶部导航栏
顶部导航栏的配置需要修改 src/.vuepress/navbar 目录下的文件。默认会提供中英文两套配置文件，按需修改即可。配置主要就是设置导航项的文字（text）、图标（icon）和链接（link）。导航栏支持二级菜单，如果需要，可以在相应项下添加 children 节点。
侧边栏
侧边栏的配置需要修改 src/.vuepress/sidebar 目录下的文件。
配置中的 prefix 属性对应文档的实际存放目录。如果目录下还有子目录，vuepress-theme-hope 会自动生成多级侧边栏。每个目录下存放的 Markdown 文件会被渲染成具体的文章页面。
在 Markdown 文件中，正文前面的 Frontmatter 区域（被 --- 包裹）用于配置文章的标题（title）、图标（icon）、排序（order）、作者（author）、日期（date）和标签（tag）等信息。正文内容直接写在 <!-- more --> 分隔符之后即可。
文档的文件名会直接影响最终生成页面的链接路径，建议使用全英文命名。我之前使用中英文混合命名时，在打包阶段偶尔会遇到一些奇怪的错误。
项目中用到的图片等静态资源，可以存放在 src/.vuepress/public 目录下。如果需要为页面或导航项寻找图标，可以查阅 vuepress-theme-hope 官方文档中关于使用 iconfont 的说明。个人实测，即使有 CDN 加持，iconfont 生成的在线 CSS 链接加载也可能比较缓慢，所以我最后选择了使用主题内置的一些默认图标。
当内容和配置都完成后，就可以准备部署了。下面提供两种方案：部署到自己的服务器和使用 GitHub Pages 白嫖。
方案一：打包并部署到个人服务器
如果你有前端部署经验，可以跳过本节。这部分主要是写给像我这样的前端小白参考的。
我因为有一台闲置的服务器，所以首先想到的是部署到自己的服务器上。由于缺乏经验，我最初尝试用 nohup 配合 yarn run docs:dev 命令将开发服务器启在后台。但不知为何，这个进程在我关闭 SSH 客户端后不久就会被杀死。
咨询了前端同事后得知，正确做法是将项目打包后的产物（dist 目录）放到 Nginx 这类 Web 服务器下运行。
首先，在本地使用以下命令进行打包，打包产物位于 src/.vuepress/dist 目录：
yarn run docs:build
打包完成后，将 dist 目录下的所有文件上传到服务器。建议先压缩再上传，能节省时间。当然，你也可以直接在服务器上执行打包命令，我是因为服务器配置较低才选择在本地打包。
在服务器上使用 unzip 命令解压后，修改 Nginx 的配置文件，将 root 直接指向解压后的 dist 目录：
server {
listen 8080;
server_name localhost;
location / {
root /home/hydra/dist;
index index.html index.htm;
try_files $uri $uri/ /index.html;
}
}
修改完成后，重启 Nginx 使配置生效：
./nginx -s reload
如果你使用的是云服务器，通常还需要在云平台的安全组或防火墙规则中开放对应的端口（例如这里的 8080）。完成后，就可以通过浏览器访问你的站点了。
方案二：使用 GitHub Pages 自动部署
如果不想使用自己的服务器，完全可以“白嫖” GitHub 的资源。这个方案依赖于创建项目时选择的“添加 GitHub Actions 工作流”。
首先，在 GitHub 上创建一个 公开（Public） 仓库。注意，如果你希望使用 https://<USERNAME>.github.io 这样的简洁域名访问，仓库名必须严格设置为 <USERNAME>.github.io。创建仓库时 GitHub 也会有相应提示。
如果仓库名是其他名字，例如 my-blog，那么你还需要修改项目配置文件 config.ts 中的 base 选项：
export default defineUserConfig({
base: "/<REPO>/",
//...
})
同时，最终访问的地址也会变为 https://<USERNAME>.github.io/<REPO>/。
修改仓库权限配置
仓库创建好后，先别急着推送代码。我们需要先修改一个关键配置。
进入你的仓库，点击 Settings 选项卡（注意是仓库的 Settings，不是个人账户的）。然后侧边栏找到 Actions -> General，页面下拉找到 Workflow permissions 部分，选择 Read and write permissions 选项，最后点击保存。
推送代码并触发部署
完成权限设置后，就可以将本地代码推送到 GitHub 仓库了。推送完成后，点击仓库顶部的 Actions 选项卡。如果一切顺利，稍等片刻就能看到两个工作流执行成功。
如果流程执行失败，可以点击进入查看具体报错日志，错误信息通常会定位到具体文件和行号，方便修改。例如，我之前在一个 Markdown 文件里写错了日期格式，就在这里导致了编译失败。
设置 GitHub Pages 源分支
我们在前面手动打包时已经知道，构建产物位于 src/.vuepress/dist/ 目录下。而项目中预设的 GitHub Actions 工作流会自动执行构建，并将 dist 目录下的内容推送到一个名为 gh-pages 的分支。因此，我们需要告诉 GitHub Pages 从这个分支获取页面内容。
再次进入仓库的 Settings，找到 Pages 选项。在 Build and deployment -> Source 部分，将分支选择为 gh-pages。
在项目仓库中切换到这个 gh-pages 分支，可以看到里面存放的正是构建生成的 HTML、CSS、JavaScript 等静态文件：
切换部署分支后，GitHub 通常会立即重新触发一次工作流。等待片刻，你就可以使用 https://<USERNAME>.github.io 这个域名访问你的站点了。此后，每次你修改代码并推送到主分支，都会自动触发工作流，实现站点的自动更新。
总结
总的来说，使用 vuepress-theme-hope 搭建文档站或博客非常简单，大部分工作都是配置性的，几乎不需要编写前端代码，对新手非常友好。其预设的页面样式美观，响应式布局在手机、平板等小屏幕设备上也有不错的显示效果。
在搭建过程中，如果遇到具体的配置细节问题，多翻阅 官方文档 基本都能找到答案。希望这篇 GitHub Pages 和服务器部署的实践指南能帮你快速上手。如果你在搭建过程中有更多心得，也欢迎在 云栈社区 分享交流。
发表于 10 小时前
|
查看: 2|
回复: 0
