🎃 不忽悠大家哈，如果有小白的话，不知道 Vuepress 是做什么的话，这里就需要注意一下了。Vuepress 是搭建的静态网站，用户不能对网页内容进行更改，因为它不会连接数据库，就算你对网站内容进行了修改，其他人也获取不到你修改后的内容，只有网站的发布者能进行更改。所以这种类型的网站通常就是相当于公告，比如 vue 文档，就可以是一个静态网站，因为用户不需要对网站内容进行更改。

了解了一下我们要做的网站大概是什么类型的之后，下面就开始传授知识了！

我将这篇文章分为了两个部分 ------ 讲解 Vuepress 和 使用 Vuepress，各位可以根据自己的需求来选择性阅读。

前一个部分是了解 Vuepress 的，这能为我们之后打造各种各样的网站提供了基础，授人以鱼不如授人以渔对吧？
后一个部分我们会使用 vuepress 市场的主题来快速搭建我们的网站，我们只需提供内容即可。

在网站搭建好了之后，我们会使用 GitHub 提供的 GitHub Pages 功能，将我们的网站进行发布，这样别人就可以访问了。如果还有不能访问 GitHub 的游子，请科学上网。需要科学上网的朋友我可以考虑帮助一下😁

大伙有没有过打造自己的网站的梦想？不知道大家有没有，反正我是有的，并且我也付出了实践。

前端：GitHub -- huadiao-user By flower0wine

后端：GitHub -- huadiao-back-end By flower0wine

1. Vuepress 的用法

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown -- 维基百科来书写内容（如文档、博客等），然后 VuePress 会帮助你生成一个静态网站来展示它们。

好，多的不说，下面我们先不管 Vuepress 的其他的使用细节。先创建一个项目（你也可以在这个网站在线体验 Vuepress ）：

1.1. 安装

创建项目前请检查你的依赖：

Node.js v18.16.0+
包管理器，例如：npm，下面我将使用 npm 来安装各种的包。

1.2. 创建项目

首先我们得为项目设置一个位置，源代码项目通常来说就是一个文件夹，该文件夹所在的文件路径最好不要包含中文，要是包含中文了出事我可不负责哈 ~

定义好了项目文件夹后，我们就可以使用 npm 对项目进行初始化了，有两种方式对项目进行初始化（第一次使用推荐先试试第二种）：

1.2.1. 创建项目模板

在终端中输入下面的命令来快速初始化一个项目（新手建议使用第二种方式来熟悉）：

shell 复制代码

npm init vuepress vuepress-starter

1.2.2. 手动创建项目

首先使用 npm 来初始化项目，它会创建一个 package.json 文件。

shell 复制代码

npm init -y

然后我们使用 npm 来安装 Vuepress 包，具体的命令如下：

shell 复制代码

# 安装 vuepress
npm install -D vuepress@next
# 安装 vite 打包工具和 vuepress 默认主题
npm install -D @vuepress/bundler-vite@next @vuepress/theme-default@next

再创建 docs 和 docs/.vuepress 目录：

shell 复制代码

mkdir docs
mkdir docs/.vuepress

最后再创建配置文件 docs/.vuepress/config.js，该文件的内容如下：

js 复制代码

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
    bundler: viteBundler(),
    theme: defaultTheme(),

    lang: 'zh-CN',
    title: '安静的闹市',
    description: '世界上的坏人坏事太多了，似乎使我们变得麻木了？',
});

为了让我们的网站有一点的内容，还需要创建一个 docs/README.md 文件，你可以在其中输入以下内容：

md 复制代码

# 自个儿的网站

网站没有任何的内容，但是有大家的浏览量！这个空壳网站也变得热闹了起来。

创建完之后你的文件结构应该会是这个样子：

lua 复制代码

|---- package.json
|---- node_modules
|---- docs
       |---- .vuepress
       |         |---- config.js
       |---- README.md

这就是 Vuepress 项目的基本文件结构了，接下来我们尝试将这个项目跑起来。

1.3. 运行项目

首先在 package.json 的 script 配置项中添加下面的脚本：

json 复制代码

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

// 如果有端口占用的问题，为 docs:dev 后面的内容添加 --port 来制定运行的端口，如：
// vuepress dev docs --port 9090

配置好后执行下面的命令来启动具备 热重载 的开发服务器：

shell 复制代码

npm run docs:dev

1.4. 配置页面

Vuepress 为我们提供了两种配置方式，一种是在 docs/.vuepress/config.js 中配置，还有一种是在 markdown 文档中配置，不过我认为前一种更好，因为有提示嘛~

所以我们就只介绍前面一种配置的方式，另外一种如果你感兴趣，请查看 Vuepress -- Frontmatter。

1.4.1. 站点配置

1.4.1.1. base（基础路径）

base 默认为 "/"，如果你想将你的网站部署到 https://love.github.io/you/，那么 base 应该被设置成 "/you/"。

js 复制代码

export default defineUserConfig({
    base: "/you/",
});

1.4.1.2. lang（网站语言）

默认值为 en-US，该属性会对应到 html 标签的 lang 属性。

js 复制代码

export default defineUserConfig({
    lang: "zh-CN",
});

1.4.1.3. title（网站标题）

它将会作为所有页面标题的后缀，并且在默认主题的导航栏中显示。

js 复制代码

export default defineUserConfig({
    title: "今天是疯狂星期四！",
});

1.4.1.4. description（网站描述）

该属性将会作为 <meta name="description" /> 标签的 content 属性的值。

js 复制代码

export default defineUserConfig({
    description: "漂亮姐姐帮弟弟敲代码，因为不小心删除了弟弟写了大半年的爬虫程序，弟弟受不了了，于是......",
});

1.4.1.5. head

默认值为 [ ] ，在最终渲染出的 HTML 的 <head> 标签内加入的额外标签。

具体的格式为:

js 复制代码

[
    标签名（tagName）, 
    { 
        属性名（attrName）: 属性值（attrValue） 
    }, 
    标签内容（innerHTML，可选）
]

需要注意的是，如果 attrValue 是一个路径，它不会被自动添加 base 前缀，只能手动添加。

例如：

js 复制代码

export default {
  head: [['link', { rel: 'icon', href: '/images/logo.png' }]],
}

渲染为

html 复制代码

<head>
  <link rel="icon" href="/images/logo.png" />
</head>

1.4.2. 配置导航栏

navbar 配置项可以接收两种类型的值：

false：禁用导航栏
[ ] ：数组中可以填写的类型有 NavbarItem | NavbarGroup | string
- NavbarItem ：具有 text 和 link 字段，还有个可选的 activeMatch 字段
- NavbarGroup ：具有 text 和 children 字段，children 字段同样是一个导航栏数组，可以填写 NavbarItem | NavbarGroup | string 三种类型。
- string：字符串应为目标页面文件的路径。它将会被转换为 NavbarItem 对象，将页面标题作为 text，将文件路径作为 link。

navbar 默认值为 [ ]。

docs/.vuepress/config.js

js 复制代码

import { defaultTheme } from '@vuepress/theme-default';
import { defineUserConfig } from 'vuepress';

export default defineUserConfig({
    theme: defaultTheme({
        navbar: [
            // NavbarItem，内容仅供参考
            {
                text: "先生的故里",
                link: "/hometown/", 
            }, 
            
            // NavbarGroup
            {
                text: "总理为民的一生",
                children: ["/group/README.md", "/group/life.md"],
            },
            
            // string
            "/ElonReeveMusk/README.md",
        ],
       
    }),
});

导航栏的基本配置就是上面这样，根据你的需要来选择一种方式来定义即可。我们使用的最多是 NavbarItem 和 NavbarGroup 这两种类型。

1.4.3. 配置侧边栏

sidebar 配置项接收四种类型的值：

false: 禁用侧边栏。
'auto'：侧边栏会根据页面标题自动生成。
SidebarConfigArray ：该类型为数组，其中每一项都是 SidebarItem 对象或者是字符串。
- SidebarItem 包含一个必填的 text 字段，一个可选的 link 字段，一个可选的 children 字段和一个可选的 collapsible 字段。children 字段同样是一个侧边栏数组。 collapsible 字段来控制它是否可折叠。
- 字符串应为 md 文件的路径。它将会被转换为 SidebarItem 对象，将页面标题作为 text ，将文件路径作为 link ，并根据页面小标题自动生成 children 。

js 复制代码

export default {
  theme: defaultTheme({
    // 所有页面会使用相同的侧边栏
    sidebar: [
      // SidebarItem
      {
        text: "生死有命",
        link: '/die/',
        children: [],
      },
      // md 文件路径
      '/life/README.md',
    ],
  }),
}

SidebarConfigObject：如果你想在不同子路径中使用不同的侧边栏，你可以将该配置项设置为侧边栏对象：
- 键名通常为 md 文件所在的目录名。
- 键值为侧边栏数组或字符串 "heading"，当键值为 "heading" 时会以 md 文件中的标题来生成相应的侧边栏。

js 复制代码

export default {
  theme: defaultTheme({
    // 不同子路径下的页面会使用不同的侧边栏
    sidebar: {
      '/hero/': [
        {
          text: '英雄',
          children: ['/hero/AntidrugPolice.md', '/hero/Firefighter.md'],
        },
      ],
      '/auto/': 'heading',
    },
  }),
}

1.4.4. 配置 logo

logo 配置项设置为 null 会禁用 logo，此外还可以设置为字符串。

js 复制代码

export default {
  theme: defaultTheme({
    // 会读取 public/images/hero.png
    logo: '/images/hero.png',
    // URL
    logo: 'https://vuejs.org/images/logo.png',
  }),
}

这是我使用 Vuepress 的默认主题搭建的一个静态网站：
GitHub Pages 在线预览
 Vuepress 默认主题源码地址

2. Vuepress 搭建博客

如果你想快速搭建一个博客，这里建议你使用一个 VuePress 市场中的主题，你只需要替换凋其中的内容即可。

下面我们主要是带领大家整合一下 Vuepress 主题和 Vuepress 插件，来增加、增强我们网站的功能。

我们搭建的网站示例的主题是 Vuepress-theme-hope

2.1. 使用 Vuepress-theme-hope 主题

啥？你问我为什么选择这个主题？emm...因为我从这个主题中看到了希望！！字面意思上，哈哈~

2.1.1. 初始化项目

在初始化项目前，请检查你的路径是否包含中文，建议使用纯英文路径。

在项目文件夹中，运行下面的命令:

shell 复制代码

npm init vuepress-theme-hope 项目名
# 例如
npm init vuepress-theme-hope project

运行上面的命令，会让你进行一系列的选择，结束后项目文件会在 project 文件夹下生成。

2.1.2. 项目命令

在项目的 package.json 的 script 配置项中你可以看到以下三个配置：

json 复制代码

"docs:build": "vuepress build src",
"docs:clean-dev": "vuepress dev src --clean-cache",
"docs:dev": "vuepress dev src"

npm docs:dev 会启动一个开发服务器，以便让你在本地开发你的 VuePress 站点。
npm docs:build 会将你的 VuePress 站点构建成静态文件，以便你进行后续部署。
npm docs:clean-dev 清除缓存并启动开发服务器。

2.1.3. 运行项目

经过我多次尝试，发现运行项目时可能会遇到两个问题：

sass-loader 包没有下载，运行命令 npm i sass-loader -D。
@waline/client 包没有下载，运行命令 npm i @waline/client，这个是一个 vuepress-plugin-comment2 依赖的包，用来实现评论功能的。

如果端口有冲突，加上 --port 参数，例如："docs:dev": "vuepress dev src --port 9092"

处理完上述问题之后，运行下面的命令即可：

shell 复制代码

npm run docs:dev

如果这个效果你就已经满意了，那么你只需对 md 文件的内容修改即可。不过我们还需要增强网站的功能，下面会集成 Vuepress 提供的插件来增强网站的功能。

2.2. 集成搜索插件

为我们的网站添加一个搜索功能，使我们的网站更加强大！

因为 docsearch 使用起来比较麻烦，而且还需要联网，而 search 不需要联网，使用起来也不麻烦，所以这里我们使用的插件是 search。

2.2.1. 安装

在终端中执行下面的命令来安装该插件。

shell 复制代码

npm i -D @vuepress/plugin-search@next

# 如果上面的命令执行时报错，可能是版本的问题，你可以看看报错的信息，然后像下面这样指定版本
npm i -D @vuepress/plugin-search@2.0.0-rc.12

2.2.2. 配置

然后在 .vuepress/config.js 中进行配置，关于该插件的配置可以查看 Vuepress 插件 --- search

js 复制代码

import { searchPlugin } from '@vuepress/plugin-search'

export default {
    // 其他配置项...
    plugins: [
        searchPlugin(),
    ],
}

效果如下：

3. GitHub Pages 部署

在终端运行下面的命令，进行构建打包。将会在 .vuepress 下生成 dist 目录，只要将这个目录下的文件上传至 GitHub 就可以了。

shell 复制代码

npm run docs:build

下面你可以使用 Git，也可以直接在 GitHub 拖动来上传文件，这里我的路径跟大家的不一样，总之使用 git 上传肯定是更方便的、更快的。

基本的命令就是下面这样，如果使用 IDE 就不用输入相关的命令，直接就是鼠标操作。

shell 复制代码

# 添加文件到暂存区
git add <文件>

# 提交变更到本地仓库
git commit -m "相关信息"

# 推送到远程仓库
git push <远程仓库 URI> <本地分支>:<远程分支>

然后点击仓库的 setting 选项。

找到 pages 选项。

然后点击下图中的按钮。并选择你要发布的分支 （比如 main 分支），并点击 save 按钮即可，之后刷新你就能看到你的页面被发布了。

发布成功的效果如下图所示：

项目源码地址：GitHub -- vuepress-theme-hope

项目预览地址：GitHub Pages -- vuepress-theme-hope

4. 结语

至此文章到这就结束了，不知对你有没有帮助。希望各位都能拥有自己的小网站，当然这是静态网站，相信如果是记录一下自己的学习成果还是没问题的。

最后祝大家新年快乐！🎈🎁

今天！带你部署自个儿的网站！🔥【Vuepress2 + GitHub Pages】

1. Vuepress 的用法

1.1. 安装

1.2. 创建项目

1.2.1. 创建项目模板

1.2.2. 手动创建项目

1.3. 运行项目

1.4. 配置页面

1.4.1. 站点配置

1.4.1.1. base（基础路径）

1.4.1.2. lang（网站语言）

1.4.1.3. title（网站标题）

1.4.1.4. description（网站描述）

1.4.1.5. head

1.4.2. 配置导航栏

1.4.3. 配置侧边栏

1.4.4. 配置 logo

2. Vuepress 搭建博客

2.1. 使用 Vuepress-theme-hope 主题

2.1.1. 初始化项目

2.1.2. 项目命令

2.1.3. 运行项目

2.2. 集成搜索插件

2.2.1. 安装

2.2.2. 配置

3. GitHub Pages 部署

4. 结语