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

最新推荐文章于 2024-04-06 19:59:23 发布

知半愚无

最新推荐文章于 2024-04-06 19:59:23 发布

阅读量1k

点赞数 23

文章标签： github

本文链接：https://blog.csdn.net/weixin_64433668/article/details/136122151

版权

🎃 不忽悠大家哈，如果有小白的话，不知道 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. 创建项目模板

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

npm init vuepress vuepress-starter

1.2.2. 手动创建项目

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

npm init -y

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

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

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

mkdir docs
mkdir docs/.vuepress

最后再创建配置文件 docs/.vuepress/config.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 文件，你可以在其中输入以下内容：

# 自个儿的网站

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

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

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

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

1.3. 运行项目

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

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

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

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

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/"。

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

1.4.1.2. lang（网站语言）

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

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

1.4.1.3. title（网站标题）

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

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

1.4.1.4. description（网站描述）

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

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

1.4.1.5. head

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

具体的格式为:

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

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

例如：

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

渲染为

<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

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 。

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

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

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

1.4.4. 配置 logo

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

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. 初始化项目

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

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

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

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

2.1.2. 项目命令

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

"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"

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

npm run docs:dev

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

2.2. 集成搜索插件

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

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

2.2.1. 安装

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

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

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

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

效果如下：

3. GitHub Pages 部署

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

npm run docs:build

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

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

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

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

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

然后点击仓库的 setting 选项。

找到 pages 选项。

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

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

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

4. 结语

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

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

知半愚无

关注

23
点赞
踩
27

收藏

觉得还不错? 一键收藏
1
评论
今天！带你部署自个儿的网站！【Vuepress2 + GitHub Pages】

至此文章到这就结束了，不知对你有没有帮助。希望各位都能拥有自己的小网站，当然这是静态网站，相信如果是记录一下自己的学习成果还是没问题的。最后祝大家新年快乐！🎈🎁。
复制链接

扫一扫