mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
182 lines
5.5 KiB
Markdown
182 lines
5.5 KiB
Markdown
---
|
||
title: 常见问题
|
||
createTime: 2024/09/27 08:47:36
|
||
permalink: /faq/
|
||
article: false
|
||
---
|
||
|
||
本文主要包含了使用主题的过程中可能会遇到的常见问题与解决方法。
|
||
|
||
如果您遇到任何问题，您可以先在以下内容中寻找是否有相关的问题和解决方法。
|
||
|
||
如果没有找到，您可以先通过 Github [Discussions](https://github.com/pengzhanbo/vuepress-theme-plume/discussions/new?category=q-a) 与我们讨论。
|
||
|
||
如果您确定某处确实存在问题，请在 Github [Open an issue](https://github.com/pengzhanbo/vuepress-theme-plume/issues/new?assignees=pengzhanbo&labels=bug&projects=&template=bug-report.zh-CN.yml&title=%5BBug%5D),
|
||
在 Issue 中说明该问题的具体细节，如有必要，请尽量提供一个 最小重现包，我们会尽快解决。
|
||
|
||
::: details 发起讨论或提出问题需要注意什么？
|
||
我们欢迎你发起讨论或提出任何问题，无论它是否简单，积极提问是好事。但请确保以下三点：
|
||
|
||
1. 你已经尝试搜索过相关文档；
|
||
2. 你在讨论中提供了详细的描述；
|
||
3. 你不是在问与 VuePress 无关的问题，也不是在寻求技术支持。
|
||
|
||
我们不会回答 “我如何在我自己的项目中单独使用主题的某个功能” 、“我怎么在我的自己项目中实现主题的某个功能” 这种
|
||
问题。
|
||
:::
|
||
|
||
## 怎么更新主题？
|
||
|
||
你可以通过 `vp-update` 命令来更新主题。
|
||
|
||
`vp-update` 是 VuePress 官方维护的 CLI 工具，它可以帮助你检查项目内与 VuePress 相关的主题、插件等的
|
||
最新版本，并自动为你安装依赖。
|
||
|
||
复制以下命令到你的项目中运行：
|
||
|
||
::: npm-to
|
||
|
||
```sh
|
||
npx vp-update
|
||
```
|
||
|
||
:::
|
||
|
||
## 为什么更新主题版本后新的功能没有生效？
|
||
|
||
由于 VuePress 在启动开发服务时，全量编译源目录中的的 `markdown` 文件耗时较长，主题对 `markdown` 的编译进行了
|
||
缓存，以提高启动速度。主题更新后重启开发服务时，由于源目录中的 `markdown` 文件没有变化，跳过了编译直接使用缓存，
|
||
这会导致与 markdown 有关的新功能没有生效。
|
||
|
||
**只需要删除缓存文件，并重启即可**：
|
||
|
||
1. 方法一：直接删除 `.vuepress/.cache` 目录。
|
||
2. 方法二：在启动开发服务命令后面，添加 `--clean-cache` 参数：
|
||
|
||
```sh
|
||
vuepress dev docs --clean-cache
|
||
```
|
||
|
||
## 为什么修改主题插件的配置没有生效？
|
||
|
||
这个文件常见于修改 `plugins.markdownEnhance` 、`plugins.markdownPower` 、`plugins.markdownImage` 和
|
||
`plugins.markdownMath` 的配置。它与 [为什么更新主题版本后新的功能没有生效？](#为什么更新主题版本后新的功能没有生效)
|
||
的原因相同。因此
|
||
|
||
**只需要删除缓存文件，并重启即可**：
|
||
|
||
1. 方法一：直接删除 `.vuepress/.cache` 目录。
|
||
2. 方法二：在启动开发服务命令后面，添加 `--clean-cache` 参数：
|
||
|
||
```sh
|
||
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` 字段来隐藏页脚。
|
||
|
||
```md title="post.md"
|
||
---
|
||
footer: false
|
||
---
|
||
|
||
content
|
||
```
|
||
|
||
[配置文档：**frontmatter > 页脚**](./config/frontmatter/basic.md#footer){.read-more}
|
||
|
||
或者在主题配置文件中，添加 `footer: false` 字段来隐藏整个主站所有页面的页脚。
|
||
|
||
```ts title=".vuepress/config.ts"
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
footer: false, // [!code ++]
|
||
})
|
||
})
|
||
```
|
||
|
||
[配置文档：**主题配置**](./config/theme.md#footer){.read-more}
|
||
|
||
## 构建时错误：`JavaScript heap out of memory`
|
||
|
||
在执行 `npm run docs:build` 时，出现类似以下错误：
|
||
|
||
```sh
|
||
<--- 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 内存限制：
|
||
|
||
**方式一 在当前命令行工具的会话期内**：
|
||
|
||
```sh
|
||
export NODE_OPTIONS="--max_old_space_size=8192"
|
||
npm run docs:build
|
||
```
|
||
|
||
==注意此方式仅在当前命令行工具的会话期内有效。=={.warning}
|
||
|
||
**方式二 在本地环境中**：
|
||
|
||
需要长期保持此环境变量，可以通过以下方式在本地环境中修改 nodejs 内存限制:
|
||
|
||
:::: steps
|
||
|
||
- 在项目中安装 `cross-env`
|
||
|
||
::: npm-to
|
||
|
||
```sh
|
||
npm install -D cross-env
|
||
```
|
||
|
||
:::
|
||
|
||
- 在 `package.json` 中添加 `scripts`:
|
||
|
||
```json
|
||
{
|
||
"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` 文件，添加以下环境变量:
|
||
|
||
```yaml
|
||
# ...
|
||
- name: Build VuePress site
|
||
env: # [!code ++:2]
|
||
NODE_OPTIONS: --max_old_space_size=8192
|
||
run: npm run docs:build
|
||
|
||
# ...
|
||
```
|