vuepress-theme-plume/questions.md at 3c4985ac1aa4ca95d5124370aaf3b07c06f18fc6

forked from gitea-yuany3721/vuepress-theme-plume

pengzhanbo 57617e6658 docs: update QA

2025-11-20 21:08:43 +08:00

5.5 KiB

Raw Blame History

title, createTime, permalink, article

title	createTime	permalink	article
常见问题	2024/09/27 08:47:36	/faq/	false

本文主要包含了使用主题的过程中可能会遇到的常见问题与解决方法。

如果您遇到任何问题，您可以先在以下内容中寻找是否有相关的问题和解决方法。

如果没有找到，您可以先通过 Github Discussions 与我们讨论。

如果您确定某处确实存在问题，请在 Github Open an issue, 在 Issue 中说明该问题的具体细节，如有必要，请尽量提供一个最小重现包，我们会尽快解决。

::: details 发起讨论或提出问题需要注意什么？我们欢迎你发起讨论或提出任何问题，无论它是否简单，积极提问是好事。但请确保以下三点：

你已经尝试搜索过相关文档；
你在讨论中提供了详细的描述；
你不是在问与 VuePress 无关的问题，也不是在寻求技术支持。

我们不会回答 “我如何在我自己的项目中单独使用主题的某个功能” 、“我怎么在我的自己项目中实现主题的某个功能” 这种问题。 :::

怎么更新主题？

你可以通过 vp-update 命令来更新主题。

vp-update 是 VuePress 官方维护的 CLI 工具，它可以帮助你检查项目内与 VuePress 相关的主题、插件等的最新版本，并自动为你安装依赖。

复制以下命令到你的项目中运行：

::: npm-to

npx vp-update

:::

为什么更新主题版本后新的功能没有生效？

由于 VuePress 在启动开发服务时，全量编译源目录中的的 markdown 文件耗时较长，主题对 markdown 的编译进行了缓存，以提高启动速度。主题更新后重启开发服务时，由于源目录中的 markdown 文件没有变化，跳过了编译直接使用缓存，这会导致与 markdown 有关的新功能没有生效。

只需要删除缓存文件，并重启即可：

方法一：直接删除 .vuepress/.cache 目录。
方法二：在启动开发服务命令后面，添加 --clean-cache 参数：
```
vuepress dev docs --clean-cache
```

为什么修改主题插件的配置没有生效？

这个文件常见于修改 plugins.markdownEnhance 、plugins.markdownPower 、plugins.markdownImage 和 plugins.markdownMath 的配置。它与为什么更新主题版本后新的功能没有生效？的原因相同。因此

只需要删除缓存文件，并重启即可：

方法一：直接删除 .vuepress/.cache 目录。
方法二：在启动开发服务命令后面，添加 --clean-cache 参数：
```
vuepress dev docs --clean-cache
```

更新依赖后重启提示 `import "xxxx" not exist`

有时候更新主题以及相关依赖后，可能会存在包管理器未能正确生成新的依赖树的问题，导致了导入一些依赖时，提示找不到该依赖的错误。这时候的依赖锁定文件如 package-lock.json 或 pnpm-lock.yaml 已经被污染。

请直接删除 package-lock.json 或 pnpm-lock.yaml 等依赖锁定文件，以及删除 node_modules 目录，然后重新安装依赖。

怎么隐藏页面的页脚？

可以在 Markdown 文件的 frontmatter 中，添加 footer: false 字段来隐藏页脚。

---
footer: false
---

content

配置文档：frontmatter > 页脚{.read-more}

或者在主题配置文件中，添加 footer: false 字段来隐藏整个主站所有页面的页脚。

export default defineUserConfig({
  theme: plumeTheme({
    footer: false, // [!code ++]
  })
})

配置文档：主题配置{.read-more}

构建时错误：`JavaScript heap out of memory`

在执行 npm run docs:build 时，出现类似以下错误：

<--- Last few GCs --->

[69161:0x7fe63aa00000]   137006 ms: xxxxxx
[69161:0x7fe63aa00000]   139327 ms: xxxxxxxx

<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----

1: 0x107ce7c84 xxxxxxxxxxxx
...

这是由于 nodejs 内存不足导致。

通过添加以下环境变量，修改 nodejs 内存限制：

方式一在当前命令行工具的会话期内：

export NODE_OPTIONS="--max_old_space_size=8192"
npm run docs:build

==注意此方式仅在当前命令行工具的会话期内有效。=={.warning}

方式二在本地环境中：

需要长期保持此环境变量，可以通过以下方式在本地环境中修改 nodejs 内存限制:

:::: steps

在项目中安装 cross-env

::: npm-to
```
npm install -D cross-env
```
:::

在 package.json 中添加 scripts:

{
  "scripts": {
    "docs:build-local": "cross-env NODE_OPTIONS=\"--max_old_space_size=8192\" vuepress build docs --clean-cache --clean-temp"
  }
}

::::

在本地构建时，使用 npm run docs:build-local 构建包。

方式三在 Github Actions 中：

修改 .github/workflows/deploy.yml 文件，添加以下环境变量:

# ...
- name: Build VuePress site
  env: # [!code ++:2]
    NODE_OPTIONS: --max_old_space_size=8192
  run: npm run docs:build

# ...

5.5 KiB Raw Blame History Unescape Escape