常见问题

约 344 字大约 1 分钟

2026-01-13

页面报错问题

当执行 npm run docs:dev 后，打开页面时出现如下错误：

[plugin:vite:import-analysis] Failed to parse source for import analysis because the content contains invalid JS syntax. If you are using JSX, make sure to name the file with the .jsx or .tsx extension.

原因分析

冲突来源：
VuePress 核心：检测到 docs/guide/README.md 文件，会自动生成 /guide/ 路由的页面。
Plume 主题配置：原配置中 guide 被设为 type: 'post' 。在 Plume 中， post 类型（通常用于博客列表）会自动生成一个索引页面到 linkPrefix 指定的路径（即 /guide/ ）。
文件损坏：
在执行 npm run docs:dev 进行初始构建时，这两个进程（VuePress 核心和 Plume 集合生成器）同时试图写入同一个临时文件 docs/.vuepress/.temp/pages/guide/index.html.js 。
这导致了文件内容的追加/混合（即你看到的“渲染异常”或文件内有两段代码），从而引发浏览器端的 JS 错误。
为什么编辑保存后正常？
当你直接编辑并保存文件时，触发的是 HMR（热更新）流程。此时通常只有 VuePress 核心针对该文件的更新逻辑在运行，它会覆盖掉错误的临时文件，从而恢复正常。

解决方案

修改docs/guide/README.md 文件名为其它。
修改 VuePress 配置文件 config.js ，将 guide 集合的 type 从 'post' 改为 'doc'。