VitePress项目构建问题记录-可能遇到的问题以及解决方法

随笔VitePress

内容概要

构建VitePress仓库时遇到安装依赖失败、构建也失败的问题。可能的原因包括下载Playwright的脚本失败，缺失相关的包从而产生未知指令错误，项目的补丁没有正确安装等等。

此页面记录了我在构建VitePress项目时遇到的问题。

安装依赖

参照VitePress的贡献指南，其使用了pnpm作为包管理器，故需要pnpm环境。

下载依赖包的过程中，我这里没有出现问题。然而，依赖安装完毕之后，它又开始自动运行Playwright安装脚本。我这里始终无法完成Playwright的下载，到最后发现是因为它请求了一个不存在的资源playwright chromium-headless-shell v1208。

对此，只需使用--ignore-scripts选项，忽略安装过程中的脚本，即可完成依赖安装。

pnpm install --ignore-scripts

构建项目

这里的说的“构建”，其实就是指运行pnpm run docs命令来启动本地服务器。

最开始我构建时，总是构建失败，并且能在命令行输出中看到类似“未知的命令xxx”这样的提示这个提示有时候还会乱码。后来发现，其实就是缺少了相关的包，直接运行指令npm install -g xxx全局安装相关的包就好。（可能需要全局安装好几个）

然而，构建输出里还是有错误，说什么“模块markdown-it-attrs不包含导出项MarkdownItAttrsOptions”类似这样的话。然而，我在markdown-it-attrs的代码里并没有找到MarkdownItAttrsOptions这个关键字。一开始我想着可能是因为这个插件更新了，后来才发现，原来这个关键字是VitePress自己定义的。VitePress项目里有一个patches文件夹，可见它是用了pnpm的补丁功能的。在一个补丁中，它自定义了MarkdownItAttrsOptions这样一个接口。

pnpm的补丁是在安装依赖时自动应用的。如果之前安装依赖的操作因为下载Playwright失败而中断，就不会应用这些补丁，自然也就找不到这个在补丁中自定义的关键字。只要依照前面说的，忽略脚本并完成安装即可。