vitepress从0开始部署笔记

前置知识

1、什么是SSG

SSG：Static site generators ，即静态站点生成器。用户在本地写markdown，即可通过SSG生成一个静态站点，生成后只有纯前端内容，不需要服务端处理，在运行时会更快。

缺点：

对数据的任何更改都需要进行完全重建
不适用于需频繁更新网站内容，实时、动态数据的情况。例如，股票交易或内容需要不断更新的 SaaS 仪表板

总结，它是前端开发技术，不涉及到后端开发。

2、有什么用

非常适合写个人博客网站，技术文档、API文档、手册等。

比如vue全家桶工具文档，如vitepress的官网：https://vitepress.dev/

比如elementUI开发文档：https://element-plus.org/zh-CN/

3、目前流行的SSG有哪些

Next.js 、 Gatsby 非常适合 React 开发者
Nuxt.js 、vuepress、vitepress非常适合 Vue.js 开发者
SvelteKit 非常适合 Svelte 开发者
Hugo 非常适合 Go 开发者
Astro 支持静态页面生成 (SSG) 和服务器端渲染 (SSR)，可以按需渲染内容
Jekyll 一个简单的静态网站生成器，用于生成个人，项目或组织的网站，原先被github推荐使用

4、为什么选择vitepress

基于vue.js，易于上手，适合大部分人，有详细的官方文档，甚至非程序开发人员也能根据官方文档快速搭建
VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。
Vue 团队决定将重点放在 VitePress，作为长期的主要SSG选择推荐

一、在本地安装vitepress

前置条件：需安装Node.js 16 及以上版本，建议使用node最新版。

按照官网说明，可以嵌入到当前项目安装或独立为一个vitepress项目。

即有两种使用场景：

场景1，二级目录安装。比如我开发了一个web项目，需要为这个项目添加使用文档或接口文档，那么我就可以在这个项目新建一个docs文件夹，在该文件夹中安装、运行和部署vitepress（实际上它与该web项目还是独立的），比如vue官方的pinia等库。
场景2，独立安装。比如我想将vitepress当做一个技术博客(blog)，那么就可以新建一个全新的根文件夹，然后安装vitepress。

但是不管是哪种方式，安装命令都是一样的。这里为了方便操作，我以场景2为例。

首先新建一个文件夹，然后在文件夹里面运行powerShell等命令行工具，以便命令行工具能定位到该文件夹下。

安装步骤如下：

1、安装为一个依赖包

bash

npm add -D vitepress

这样在当前文件夹下会新建一个node_modules文件夹和一个package.json，当然还会有package-lock.json.

2、初始化vitepress

bash

npx vitepress init

将需要回答几个简单的问题：

json

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└  Done! Now run npm run docs:dev and start writing.

重点关注第二个问题，./docs 它会在刚刚的全新文件夹下创建一个新的docs文件夹，这个可以理解为vitepress的根目录。config和markdown等文档都放置在此。

以上可参考官网：https://vitepress.dev/zh/guide/getting-started

二、在本地运行vitepress

就像步骤1最后的提示那样，我们可以在本地通过如下命令来预览新建好的静态站点。

bash

npm run docs:dev

运行成功后，会在你默认的浏览器中打开一个域名，比如：http://localhost:5173/

最终的效果如下：

三、在本地书写markdown和简单的配置

1、新建文档和markdown文件

统一在docs中新建一个文件夹，比如我们要存放guide的文档。

然后在该文件夹下新建一个markdown文件，在markdown中编写内容、代码等。

例如：

bash

.
├─ guide
│  ├─ getting-started.md
│  └─ index.md
├─ index.md
└─ prologue.md

2、配置访问地址（导航菜单）

vitepress启动本地开发后，支持热更新，也就是说内容更新后，会在打开的浏览器中能保持实时预览。

但是我们刚刚新建的文件并没有配置访问路径，需要配置才能看到效果。

找到docs\.vitepress\config.js下的themeConfig对象，进行如下配置：

// 顶部菜单
nav: [
    { text: "首页", link: "/" },
    { text: "指南", link: "/guide/",activeMatch: '/guide/' },
],
// 侧边栏菜单    
sidebar: {
  "/guide/": 
  { 
      base: "/guide/", 
      items: [
      { text: "首页", link: "/" }, //对应index.md
      { text: "快速开始", link: "getting-started" },//对应 getting-started.md
    ],
    collapsed: false,
  },
},

参考地址：https://vitepress.dev/zh/guide/routing

四、部署到github pages并且每次提交都能自动部署

我们新建的站点自然是希望能部署到线上，然后在任意地方都可以访问，如果自己没有服务器，那么可以将vitepress部署到github pages，享受免费的部署服务。

接下来就是实现的具体步骤。

1、首先在你的`github`中创建一个新的仓库，比如我的叫`blog`

这样我们就新建了一个空白的仓库，创建的仓库地址：https://github.com/你的用户名/blog

2、将刚刚在本地新建的`vitepress`根目录，与`github`关联，并且推送到`github`仓库

首先确保powerShell命令行工具在本地站点下，然后依次执行如下指令：

bash

git init
git add *
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/你的用户名/blog.git
git push -u origin main

这样github的空白仓库就同步了本地的站点了。

3、确定站点到底是以根站点的方式存在还是二级目录站点存在

首先确定下我们的站点到底是以根站点的方式存在还是二级目录站点存在。他们的区别就像是这样：

https://你的用户名.github.io/ (根目录)
https://你的用户名.github.io/blog/ （二级目录）

如果是后者，那么就需要修改本地站点下的 docs/.vitepress/config.mjs文件，新增base配置项：

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  lang: 'zh-CN',
  base: '/blog/',  //这里就是二级目录名字，也是github的仓库名字,如果是
  title: "My Awesome Project",
  description: "A VitePress Site",
  ....
})

4、新建`github pages`的自动部署文件

在本地站点根目录下，新建文件夹.github，再新建workflows文件夹，然后在这里面新建一个deploy.yml部署文件。

内容可以在https://vitepress.dev/zh/guide/deploy#github-pages 看到。

直接复制，不用改动任何东西。

xml

# 构建 VitePress 站点并将其部署到 GitHub Pages 的示例工作流程
#
name: Deploy VitePress site to Pages

on:
  # 在针对 `main` 分支的推送上运行。如果你
  # 使用 `master` 分支作为默认分支，请将其更改为 `master`
  push:
    branches: [main]

  # 允许你从 Actions 选项卡手动运行此工作流程
  workflow_dispatch:

# 设置 GITHUB_TOKEN 的权限，以允许部署到 GitHub Pages
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@v3
        with:
          fetch-depth: 0 # 如果未启用 lastUpdated，则不需要
      # - uses: pnpm/action-setup@v2 # 如果使用 pnpm，请取消注释
      # - uses: oven-sh/setup-bun@v1 # 如果使用 Bun，请取消注释
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm # 或 pnpm / yarn
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Install dependencies
        run: npm ci # 或 pnpm install / yarn install / bun install
      - name: Build with VitePress
        run: |
          npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
          touch docs/.vitepress/dist/.nojekyll
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: docs/.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@v2

5、将以上本地文件变动通过如下指令提交到`github`仓库，进行最后的部署配置工作。

bash

git add .
git commit -m '提交说明'
git push

6、在vitepress对应的github仓库中进行最后的配置和部署

在存储库设置中的“Pages”菜单项下，选择“Build and deployment > Source > GitHub Actions”

具体流程，可以在仓库的action面板中看到：

7、等待部署完成，就可以直接访问部署好的vitepress站点了

比如我的站点是：https://imqdcn.github.io/blog/

8、如何自动更新和部署

其实我们的工作都已经完成，你只需要在本地尽情的写作修改，然后记得及时提交到github，它就能自动部署，自动更新网站内容。这些都不需要手动操作了。

9、可能的问题

我下载依赖包最开始用的是pnpm，没有生成package-lock.json导致部署失败，这时就需要用npm生成该文件，然后它会自动部署。

10、选择手动部署

如果你不想让其他人看到你的原始代码，原始markdown等，也可以手动部署。

方法：

与自动部署就是省去了CI的配置，deploy.xml也不需要写和上传了。
在本地通过npm run docs:build构建成dist目录。
新建一个github仓库，并将dist提交同步到该仓库中
配置Pages，到新建的仓库 -> Settings -> Pages，选择分支main和root目录
过约1分钟再次进入Settings -> Pages会看到在顶部博客链接地址，直接访问即可

虽然是手动部署了，但是当github仓库更新后，它还是会自动部署新的dist目录，以确保你的内容也是新的。

五、绑定到自己的域名，并开启https

虽然https://用户名.github.io/blog/看起来挺不错，但是我们可以将其绑定到自己的域名上（无需备案域名），然后通过类似于blog.xxx.cn来访问。

你只需要按照下面的方法操作即可。

1、域名解析

登录域名服务网站，进行域名解析，比如我的域名是阿里云的，我就需要在阿里云进行解析。

只需要将你的二级域名 cname到 <user>.github.io，如下图所示：

2、到github对应的仓库中进行设置

路径：仓库-setting-pages-Custom domain

添加刚刚在阿里云解析的域名，然后开启强制的https，这样就能通过https://你的域名访问github pages站点了。

比如这里，我就可以通过https://blog.imqd.cn/来访问。

https是免费的，空间也是免费的，只有域名是自己的。

更多github pages配置问题，请参考：https://docs.github.com/zh/pages/quickstart

六、部署到vercel

其实部署到github pages和vercel可以二选一，因为他们只是服务器不同，但是站点内容都是一样的。

但是github在国内访问不稳定，可以同步部署到vercel，以便拥有一个备用访问地址。

首先确保你已经注册了vercel了：https://vercel.com/login

可以直接用自己的github账号进行注册和关联，这样更方便操作。

然后按如下步骤进行操作。

1、在`vitepress`根目录新增部署配置文件

新建一个空白的文本文件，并重命名为vercel.json，然后一字不差的复制如下代码，并提交到github中

json

{
  "cleanUrls": true,
  "framework": "vitepress",
  "installCommand": "npm install",
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist"
}

即项目大概是这样的目录结构：

2、新建 project

3、导入要部署的github仓库

如果没有看到自己的仓库，那么是因为权限不足，点击第二个红框处的链接，将对应的仓库加进来就可以看到了。

4、点击import后，再点击deploy

5、部署成功后，就可以看到访问地址

所以只需要维护好github的仓库即可。

6、可能的问题

访问vercel站点或手动部署在github的后，样式丢失。
问题解决：
因为我们在config中是用二级目录的方式部署的，所以，如果直接点击部署，那么部署的站点会丢失样式，这样就需要我们重新配置。
可以将base中的配置重新改为‘/’ ，再重新部署即可。
反之亦然，如果你是部署到一级目录的，那么在base中就需要修改为github的仓库名，即base:"/<repository>/"静态资源才能映射成功。

vitepress从0开始部署笔记 ​

前置知识 ​

1、什么是SSG ​

2、有什么用 ​

3、目前流行的SSG有哪些 ​

4、为什么选择vitepress ​

一、在本地安装vitepress ​

二、在本地运行vitepress ​

三、在本地书写markdown和简单的配置 ​

1、新建文档和markdown文件 ​

2、配置访问地址（导航菜单） ​

四、部署到github pages并且每次提交都能自动部署 ​

1、首先在你的github中创建一个新的仓库，比如我的叫blog ​

2、将刚刚在本地新建的vitepress根目录，与github关联，并且推送到github仓库 ​

3、确定站点到底是以根站点的方式存在还是二级目录站点存在 ​

4、新建github pages的自动部署文件 ​

5、将以上本地文件变动通过如下指令提交到github仓库，进行最后的部署配置工作。 ​

6、在vitepress对应的github仓库中进行最后的配置和部署 ​

7、等待部署完成，就可以直接访问部署好的vitepress站点了 ​

8、如何自动更新和部署 ​

9、可能的问题 ​

10、选择手动部署 ​

五、绑定到自己的域名，并开启https ​

1、域名解析 ​

2、到github对应的仓库中进行设置 ​

六、部署到vercel ​

1、在vitepress根目录新增部署配置文件 ​

2、新建 project ​

3、导入要部署的github仓库 ​

4、点击import后，再点击deploy ​

5、部署成功后，就可以看到访问地址 ​

6、可能的问题 ​

vitepress从0开始部署笔记

前置知识

1、什么是SSG

2、有什么用

3、目前流行的SSG有哪些

4、为什么选择vitepress

一、在本地安装vitepress

二、在本地运行vitepress

三、在本地书写markdown和简单的配置

1、新建文档和markdown文件

2、配置访问地址（导航菜单）

四、部署到github pages并且每次提交都能自动部署

1、首先在你的`github`中创建一个新的仓库，比如我的叫`blog`

2、将刚刚在本地新建的`vitepress`根目录，与`github`关联，并且推送到`github`仓库

3、确定站点到底是以根站点的方式存在还是二级目录站点存在

4、新建`github pages`的自动部署文件

5、将以上本地文件变动通过如下指令提交到`github`仓库，进行最后的部署配置工作。

6、在vitepress对应的github仓库中进行最后的配置和部署

7、等待部署完成，就可以直接访问部署好的vitepress站点了

8、如何自动更新和部署

9、可能的问题

10、选择手动部署

五、绑定到自己的域名，并开启https

1、域名解析

2、到github对应的仓库中进行设置

六、部署到vercel

1、在`vitepress`根目录新增部署配置文件

2、新建 project

3、导入要部署的github仓库

4、点击import后，再点击deploy

5、部署成功后，就可以看到访问地址

6、可能的问题