VitePress建站教程

前言

VitePress，由Vite和Vue驱动的静态站点生成器，将Markdown变成优雅的文档，只需几分钟。

GitHub Pages是GitHub提供的一个网页寄存服务，于2008年推出。可以用于存放静态网页，包括博客、项目文档甚至整本书。一般GitHub Pages的网站使用github.io的子域名，但是用户也可以使用第三方域名。

本章介绍使用VitePress和GitHub Pages建立一个网站

VitePress官方网站：https://vitepress.dev/zh/

TIP

本章需要准备一个GitHub账户：https://github.com/signup

安装环境

安装Git

1. 打开网站：https://git-scm.com/downloads/
2. 下载并安装
3. 按下Windows徽标+X
4. 选择终端
5. 输入git -v
6. 若正常显示版本号则安装成功

安装Nodejs

1. 打开官方网站：https://nodejs.org/zh-cn
2. 下载并安装
3. 按下Windows徽标+I
4. 搜索：Powershel
5. 打开：允许本地PowerShell脚本在不签名的情况下运行
6. 开启开关：更改执行策略，以允许本地PowerShell脚本在未签名的情况下运行。远程脚本需要签名。
7. 按下Windows徽标+X
8. 点击弹出窗口中的终端
9. 输入：node -v
10. 如果正常显示版本号则成功，如果不正常就重新安装
11. 输入：npm -v
12. 如果正常显示版本号则成功，如果不正常就重新安装

安装VitePress

1. 创建并进入工作目录，如C:\用户名.github.io
2. 右键空白位置，选择在终端中打开
3. 建立Git仓库：git init
4. npm换源：npm config set registry https://registry.npmmirror.com
5. 安装VitePress：npm add -D vitepress

运行向导

1. 输入npx vitepress init
2. 大致流程如下：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./
│
◇  Site title:
│  此处填写网页名称
│
◇  Site description:
│  此处填写网页简介
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

运行网站

1. 输入npm run docs:dev
2. 随后点击输出内容的http://localhost:5173访问网站
3. 访问结束后，回到终端
4. 按下Ctrl+C结束网站

配置文件

1. 回到文件夹根目录
2. 新建以下文件或文件夹：

│ .gitignore               # GitHub忽略文件
│
└─.github
   └─workflows
      └─GitHubPages.yaml   # GitHub Actions文件

.gitignore

# VitePress的dev文件夹
.vitepress/cache/

# VitePress的build文件夹
.vitepress/dist/

# npm文件夹
node_modules/

GitHubPages.yaml

name: Deploy VitePress site to Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:


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
    - name: Setup Node
      uses: actions/setup-node@v4
      with:
        node-version: 23
    - name: Setup Pages
      uses: actions/configure-pages@v4
    - name: Install dependencies
      run: npm ci
    - name: Build with VitePress
      run: npm run docs:build
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: .vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

检查文件

│  .gitignore              # GitHub忽略文件
│  api-examples.md         # markdown文件->api-examples.html
│  index.md                # markdown文件->首页
│  markdown-examples.md    # markdown文件->markdown-examples.html
│  package-lock.json       # npm配置文件
│  package.json            # npm配置文件
│
├─.github
│  └─workflows
│          deploy.yml      # GitHub Actions文件
│
├─.vitepress               # Vitepress配置文件夹
│  │  config.mts           # Vitepress配置文件
│  │
│  └─cache                 # Vitepress的dev文件夹
└─node_modules             # npm文件夹

发布网站

1. 新建GitHub仓库：https://github.com/new
2. 仓库名称为：用户名.github.io
3. 进入仓库设置
4. 侧边栏选择Pages
5. 找到Build and deployment的Source
6. 从Deploy from a branch修改为GitHub Actions
7. 前往工作目录并打开终端命令行
8. 添加远程仓库：git remote add origin https://github.com/用户名/用户名.github.io
9. 检测本地的远程仓库配置：git remote -v
10. 推送代码，建议使用图形化软件GitHub Desktop：https://github.com/apps/desktop
11. 将工作目录C:\用户名.github.io使用add existing repository添加到GitHub Desktop中
12. 推送仓库，并等待GitHub Actions运行完毕
13. 访问https://用户名.github.io即可

进阶操作

• 编辑更多的网站信息，前往官方网站：https://vitepress.dev/zh/
• 将网站部署至服务器：部署网站至服务器