开篇：
SPA、SSR、CSR这些概念大家应该都耳熟能详，而我们今天要引出的 SSG——静态网站生成，有点像是介于 SSR 和 SPA 之间的一种模式。下面我们讲一下SSG是什么以及如何使用 VitePress 与 Github Pages 免费搭建个人网站。
一、初识 SSG：静态网站生成器的魅力
简单来说，SSG 是一种能将诸如 Markdown 文件这类内容源，结合模板与配置信息，在构建过程中提前渲染出完整 HTML 页面的工具。
与传统依赖服务器端脚本语言实时处理请求、动态生成页面的方式截然不同，它生成的静态页面可直接部署到服务器，用户访问时，服务器能迅速将对应的 HTML 文件发送过去。
传统动态网站构建与 SSG 的直观对比
在网站构建领域，传统动态网站构建方式和静态网站生成器（SSG）各有千秋。但随着技术的发展和用户体验需求的提升，两者的差异逐渐凸显，下面我们来进行详细的对比分析。
- 性能表现
传统方式在每次页面请求时，服务器都需执行数据库查询、模板渲染等一系列操作。这一过程耗时较长，尤其在高并发场景下，服务器资源被大量占用，容易出现延迟卡顿的现象，严重影响用户体验。
而 SSG 由于页面是预先构建好的，服务器无需即时渲染。当用户请求页面时，服务器可以直接返回已经生成好的静态页面，极大地减少了计算时间与网络延迟，让用户能闪电般获取页面内容。
- 安全性
从安全性角度看，传统动态网站因有服务器端脚本运行，存在诸多安全隐患，易遭受 SQL 注入、XSS 等攻击。黑客可以利用这些漏洞，非法获取用户数据或篡改网站内容，给网站所有者和用户带来严重损失。
SSG 没有活动的服务器端脚本，就如同给网站穿上一层坚固铠甲。由于不存在可被利用的服务器端脚本漏洞，有效降低了被黑客入侵的风险，为用户提供了更安全可靠的浏览环境。
- 部署便捷性
在部署方面，几乎所有 Web 主机服务商都对静态网站敞开怀抱。这是因为静态网站的部署相对简单，不需要复杂的服务器配置和维护。像 GitHub Pages 等平台还提供免费层级，方便开发者轻松托管，大大降低了网站部署的成本和门槛。
- 实际案例：以个人技术博客为例
若采用传统方式搭建个人技术博客，博主更新一篇文章后，服务器需即时处理渲染。在这个过程中，读者访问时可能要等待片刻，影响阅读体验。
但使用 SSG，博主更新内容后提前构建页面。当读者访问博客时，看到的是已经生成好的静态页面，随时访问都是秒开，能够流畅阅读知识干货。而且，由于 SSG 的安全性优势，博主无需担忧安全隐患，网站维护成本也更低，这样可以让博主能专注于创作优质内容，为读者带来更多有价值的知识分享。
综上所述，SSG 在性能、安全性和部署便捷性等方面都展现出了明显的优势，尤其适合个人技术博客等类型的网站搭建。
二、VitePress：强大的 SSG 框架
官方资源
- VitePress官方文档地址：VitePress
（一）VitePress 是什么
VitePress 是一个基于 Vite 和 Vue 的静态网站生成器（SSG），专为构建快速、以内容为中心的站点而设计。能把你用 Markdown 编写的源内容应用上主题样式，快速生成可以部署到任何地方的静态 HTML 页面。
（二）VitePress 的特色功能
- 即时热重载
因为内置了vite构建工具，在开发过程中，当修改了代码或Markdown文件，VitePress 能即时反馈，页面自动刷新。
- Markdown 支持
全面支持 Markdown 语法，无论是基础的标题、列表、链接，还是复杂的代码块、表格，都能完美呈现。并且，还允许在 Markdown 文件中直接使用 Vue 组件，为文档增添交互性。比如，你可以轻松嵌入一个 Vue 按钮组件，让原本静态的文档 “动” 起来。
---
hello: world
---
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
## Markdown Content
The count is: {{ count }}
<button class="button" @click="count++">Increment</button>
<style module>
.button {
color: red;
font-weight: bold;
}
</style>
- 主题定制
VitePress 提供了默认主题，简洁美观且实用，同时支持高度自定义主题。可以通过修改主题配置文件，自由调整颜色、字体、布局等样式，还能添加导航栏、侧边栏等个性化元素。
// 示例：修改主题元素
themeConfig: {
logo:'logo.png',
// https://vitepress.dev/reference/default-theme-config
nav: [],
sidebar: [],
socialLinks: [],
search: {},
},
三、动手搭建：使用 VitePress 搭建个人网站
（一）环境准备
- Node.js 18 及以上版本。
- 通过命令行界面 (CLI) 访问 VitePress 的终端。
- 支持 Markdown 语法的编辑器。
- 推荐 VSCode 及其官方 Vue 扩展。
node -v
安装好 Node.js 后，在命令行输入npm add -D vitepress，把 VitePress 安装到全局环境，确保随时可用：
npm add -D vitepress
（二）项目初始化
新建一个文件夹，作为你的项目根目录，比如 “vitepress”。
mkdir vitepress
cd vitepress
在终端输入npx vitepress init，一路回车默认配置，快速生成package.json文件
npx vitepress init
依提示填写配置信息，像文档目录位置（一般默认docs就行，但为了更好的项目管理，我后面会采用./根目录创建其他功能目录）、主题选择（新手推荐默认主题，后续再按需定制）。完成后查看项目目录，会发现多了.vitepress隐藏文件夹，这里面藏着配置与主题相关的重要文件。之后创建docs目录作为存放网站内容的 “素材库”。
（三）网站内容创作与配置
走进docs目录，开启内容创作：
新建 Markdown 文件，比如about.md用于写个人简介，tech.md分享技术心得。用熟悉的 Markdown 语法，尽情书写标题、段落、列表、图片、链接等，像这样：
个人简介
我是[你的名字]，热爱技术，专注于[擅长领域]。在技术探索路上，积累了诸 多经验，希望通过这个网站与大家共享 知识，共同成长。
技能专长
- 编程语言：Python、JavaScript
- 框架：Vue.js、React
- 工具：Git、Docker
欢迎随时交流，我的邮箱：[邮箱地址]。
配置导航栏与侧边栏
打开.vitepress/config.mjs（若用 TypeScript 则是.vitepress/config.mts），在themeConfig里设置nav与sidebar。nav定义顶部导航栏，sidebar设置侧边栏。
//config.mts
import { defineConfig } from 'vitepress'
export default defineConfig({
title: "Limer`s Messy World",
base: '/limer/',
description: "My werid diary, welcome to share and grow with me.",
head: ['link', { rel: 'icon', href: 'favicon.ico' }],
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '技术文章',
items:[
{ text: '前端', link: '/docs/projects' },
{ text: '后端', link: '/docs/backend' },
]},
{ text: '关于我', link: '/about' }
],
sidebar: {
'/tech': [
{
text: '前端技术',
items: [
{ text: 'Vue.js 实战', link: '/tech/vuejs-practice' },
{ text: 'React 入门', link: '/tech/react-intro' }
]
},
{
text: '后端开发',
items: [
{ text: 'Python Flask 框架', link: '/tech/python-flask' },
{ text: 'Node.js 应用', link: '/tech/nodejs-app' }
]
}
],
'/about': []
}
}
})
title、description、logo作为网站的门面信息，base是整个网站的根路由，后续与github仓库名字要保持一致，head就是标签页上面显示的图标。
导航栏选项可配置下拉子菜单，还能添加社交链接，如 GitHub、bilibili等，items不能与link同时存在。侧边栏可通过路由匹配实现不同页面不同的侧边栏，如果只要一个全局的侧边栏是这样的。
sidebar: [
{
text: '📚 Frontend Dev',
collapsed: true,
items: [
{ text: 'Vite', link: '/blogs/vite' },
]
}
],
效果展示（搜索功能实现后面会补充讲）：
（四）本地预览与调试
内容与配置就绪，在终端输入
npm run docs:dev
启动本地开发服务器,跳转到http://localhost:5173的本地访问地址。
四、借助 Github Pages：让网站上线
（一）创建 Github 仓库
首先，前往Github 官网，登录自己的账号。在右上角 “+” 号处点击，选择 “New repository”。
仓库名称务必与.vitepress/config.mts里的base命名一致，这是后续网站能正常访问的关键。
import { defineConfig } from 'vitepress'
export default defineConfig({
title: "Limer`s Messy World",
base: '/limer/',
description: "My werid diary, welcome to share and grow with me.",
})
（二）部署网站到 Github Pages
本地关联 Github 仓库：
在项目根目录下打开终端，依次执行以下命令。先初始化本地 git 仓库，输入
git init
接着添加远程仓库地址，运行
git remote add origin https://github.com/你的用户名/base路由名称（即仓库名）
执行
git add .
把项目所有文件添加到暂存区,再输入
git commit -m "Initial commit"，“Initial commit”
完成代码提交。最后运行
git push -u origin master
将本地代码推送到 Github 仓库的主分支，至此，代码就成功推送到 Github 上了。
开启 Github Pages 服务：
进入 Github 仓库页面，点击 “Settings”，在左侧菜单找到 “Pages” 选项。在 “Source” 处选择 “main” 分支（若之前推送代码到其他分支，就选对应的分支），然后点击 “Save” 保存设置。
配置.github/workflows/deploy.yml文件
在你的项目根目录创建.github/workflows目录，创建deploy.yml文件开启工作流,复制下面给的文件。
name: Deploy VitePress site to Pages
on:
push:
#分支名字
branches: [main]
# 设置tokenn访问权限
permissions:
contents: read
pages: write
id-token: write
# 只允许同时进行一次部署，跳过正在运行和最新队列之间的运行队列
# 但是，不要取消正在进行的运行，因为我们希望允许这些生产部署完成
concurrency:
group: pages
cancel-in-progress: false
jobs:
# 构建工作
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
- name: Setup pnpm
uses: pnpm/action-setup@v2 # 安装pnpm并添加到环境变量
with:
version: 8.6.12 # 指定 pnpm 版本
- name: Setup Pages
uses: actions/configure-pages@v4 # 在工作流程自动配置GithubPages
- name: Install dependencies
run: pnpm install # 安装依赖
- name: Build with VitePress
run: |
pnpm run docs:build # 启动项目
touch .vitepress/dist/.nojekyll # 通知githubpages不要使用Jekyll处理这个站点
- name: Upload artifact
uses: actions/upload-pages-artifact@v3 # 上传构建产物
with:
path: .vitepress/dist # 指定上传的路径
# 部署工作
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }} # 从后续的输出中获取部署后的页面URL
needs: build # 在build后面完成
runs-on: ubuntu-latest # 运行在最新版本的ubuntu系统上
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment # 指定id
uses: actions/deploy-pages@v4 # 将之前的构建产物部署到github pages中
采用pnpm下载依赖会更快，这样每次推送文章到你的github远程仓库就会自动部署网站，成功后会出现上面标红这一区域，点击visit site即可访问。
之后每次可以在actions标签下查看部署进度
可能出现的问题
若页面空白或样式丢失，大概率是路径配置有误，查看.vitepress/config.mts里的base配置，确保与仓库名对应。另外，样式丢失、资源文件未正确加载，要核实静态资源路径是否正确，我这里将logo之类的文件都放在了根目录的public里面。
五、总结
由于篇幅限制，本来打算写的复杂配置以及优化点就放在下一节了。至此，使用 VitePress 与 Github Pages 搭建个人网站的旅程就告一段落啦！下期见～
微信公众号：冻柠葡萄呗
