VuePress V1 踩坑记录

发布于
在这里插入图片描述

1.Node.js 版本问题

使用vuepress dev docs在本地启动服务器时报了如下错误：

代码语言：javascript
复制
Error: error:0308010C:digital envelope routines::unsupported

我用的 Node.js 版本 v18.16.0 报了上面的错误，原因是 Node.js 版本过高导致，需要将 Node.js 版本降低至 v16.x.x，比如 Node.js 16.20.0。

2.侧边栏

在 VuePress 的侧边栏分组配置中，children 的路径是相对于 docs 目录的路径，而不是相对于分组的路径。

比如有个文档路径为 docs/foo/bar.md，那么其配置如下：

代码语言：javascript
复制
// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1',      // 必要的
        path: '/foo/',         // 可选的, 标题的跳转链接，应为绝对路径且必须存在
        collapsable: false,    // 可选的, 默认值是 true,
        sidebarDepth: 1,       // 可选的, 默认值是 1
        children: ['/foo/bar'] // 必要的，如果为空，则不应该使用分组
      }
    ]
  }
}

注意，如果不显示指定链接文字，侧边栏显示的是文档的一级标题（H1）。

如果想显示地指定链接文字，使用一个格式为[path, text]的数组。

代码语言：javascript
复制
// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1',    // 必要的
        path: '/foo/',       // 可选的, 标题的跳转链接，应为绝对路径且必须存在
        collapsable: false,  // 可选的, 默认值是 true,
        sidebarDepth: 1,     // 可选的, 默认值是 1
        children: [
          ['/foo/bar', 'bar'] // 显示指定标题为 bar 而不是 /foo/bar.md 的一级标题
        ]					// 必要的，如果为空，则不应该使用分组
      }
    ]
  }
}

3.添加页面目录导航

在页面右上角添加页面目录导航栏，目的是简化左侧边栏结构的同时不丢失页面内标题导航的功能。

官方推荐的 Awesome VuePress 仓库收录的 vuepress-plugin-right-anchor 可以达到类似的效果。

注意 vuepress-plugin-right-anchor 缺省情况下目录是折叠的，需要修改配置。

代码语言：javascript
复制
expand: {
	trigger: 'hover'
}

// 改为

expand:

示例效果如下：

在这里插入图片描述

有了右侧的页面目录导航，那么我们便可以将侧边栏分组下的标题设置为只显示 H1，即将 themeConfig.sidebarDepth 设置为 0。

也可以使用 YAML front matter 来为某个页面重写此值：

代码语言：javascript
复制
---

sidebarDepth: 0

---

4.非首页 footer 不生效

VuePress 支持使用 Markdown Slot Syntax 来设置 footer，以支持富文本：

代码语言：javascript
复制
---

home: true

::: slot footer

MIT Licensed | Copyright © 2018-present Evan You

:::

当页面不是首页时，即没有开头 Front Matter 的home: true配置，那么 footer 将不生效。

一个简单的解决办法是通过 HTML 标签，比如<p>便可添加并居中显示想要的页脚。

代码语言：javascript
复制
<p align=center>

MIT Licensed | Copyright © 2018-present Evan You

</p>

我的页脚设置如下：

代码语言：javascript
复制
<p align=center style="font-size:13px;color:gray">

CC BY-NC 4.0 Licensed | Copyright © 2023-present Dable Lv

</p>

效果如下：

在这里插入图片描述

5.部署到 Github 的错误

vuepress 的 docs 与 Github Pages 的 docs 目录冲突

VuePress 默认将文档放置在项目根目录下的 docs 目录中，用于生成静态网站。它使用了一些特定的文件和目录结构，如 README.md 作为主页、.vuepress 目录用于配置等。

而 Github Pages 站点根目录可选的路径有两个，根目录 / 和 /docs。

在这里插入图片描述

如果将我们生成的静态站点内容平铺到仓库的根目录，那么会使仓库的内容显得非常凌乱，所以我们一般使用 /docs 目录。

为了解决这个冲突，我们可以将更改 VuePress 的文档目录，将 VuePress 的 docs 更名为 vuepress-docs 或者其他你喜欢的名称。需要注意的是，package.json 中的 scripts 也要做相应的修改。

代码语言：javascript
复制
{
  "name": "vuepress",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "docs:dev": "vuepress dev vuepress-docs",
    "docs:build": "vuepress build vuepress-docs"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vuepress": "^1.9.9",
    "vuepress-plugin-right-anchor": "^0.5.5"
  }
}

样式丢失

看了一下页面的 element，报了很多资源 404 的错误，所以样式丢失的原因是找不到 js 和 css 等资源。

资源加载失败，基本都是路径出了问题。查看 dist/index.html 文件可以看到，资源路径都写的是根目录下 /。

在这里插入图片描述

在 VuePress 的官方网站中， 对 config.js 中的 base 做了说明。

部署站点的基础路径，如果你想让你的网站部署到一个子路径下，你将需要设置它。如 GitHub pages，如果你想将你的网站部署到 https://foo.github.io/bar/，那么 base 应该被设置成 “/bar/”，它的值应当总是以斜杠开始，并以斜杠结束。

base 将会作为前缀自动地插入到所有以 / 开始的其他选项的链接中，所以你只需要指定一次。

所以我们修改一下 base 即可。

比如我的站点访问路径是https://dablelv.github.io/backend-cmd/，那么 base 应该配置为/backend-cmd/。

代码语言：javascript
复制
module.exports = {
  title: "后台开发命令 365",
  description: "后台开发常用命令介绍",
  base: "/backend-cmd/"
}

6.资源引用问题

本地图片找不到

Markdown 文件中引用的图片，我们可以将其统一放到与 .vuepress 目录的同级 assets/imgs 目录中，引用时我写的路径如下：

代码语言：javascript
复制
![这里写图片描述](/assets/imgs/expand/1.png)

本地预览时发现图片无法显示，原因是路径写的有问题。

官方指南对静态资源的引用已经给出说明。

所有的 Markdown 文件都会被 webpack 编译成 Vue 组件，因此你可以，并且应该更倾向于使用相对路径（Relative URLs）来引用所有的静态资源：

代码语言：javascript
复制
![An image](./image.png)

引用 CSDN 图片报 403 错误

我的博客首发在 CSDN，通过 VuePress 整理成文档网站时，很多图片引用自 CSDN，但是出现 403 Forbidden 错误无法正常显示。

由于 vuepress 生成的静态网站在拉取 CSDN 图片时，把当前网站的 referrer 带了过去，第三方发现不是本站的请求，所以直接返回 403 Forbidden 错误。

在 config.js 中添加 meta 标签，去掉 referrer。

代码语言：javascript
复制
module.exports = {
  ...
  head: [
    ['meta',{name: 'referrer',content: 'no-referrer'}]
  ],
  ...
}

添加 favicon

我将 favicon 添加到与 .vuepress 目录的同级 assets/imgs，然后在 .vuepress/config.js 中配置如下，但不生效。

代码语言：javascript
复制
['link',{rel: 'icon', href: '../assets/imgs/favicon.png'}]

查看官方文档，应该使用公共文件。

有时，你可能需要提供一个静态资源，但是它们并不直接被你的任何一个 markdown 文件或者主题组件引用 —— 举例来说，favicons 和 PWA 的图标，在这种情形下，你可以将它们放在 .vuepress/public 中， 它们最终会被复制到生成的静态文件夹中。

然后按照如下方式引用即可。

代码语言：javascript
复制
['link',{rel: 'icon', href: '/favicon.png'}]

参考文献

VuePress Global Footer in Default Theme #339 - vuejs/vuepress - GitHub vuepress2.0避坑指南 - 墨滴

#网站#vuepress#部署#后台开发#配置