常见问题
如何新增一篇文档？
- 在
docs目录下创建.md文件； - 在
docs/.vitepress/config.mjs的sidebar中登记页面路径； - 刷新浏览器即可看到新页面。
详见快速开始。
如何修改站点标题与主题色？
- 标题：修改
docs/.vitepress/config.mjs中的title； - 主题色：修改
docs/.vitepress/theme/custom.css中的--vp-c-brand-*变量。
如何启用或关闭全文搜索？
搜索配置位于 docs/.vitepress/config.mjs 的 themeConfig.search 字段，设置 provider: 'local' 启用本地搜索，移除该字段即可关闭。
文档支持深色模式吗？
支持。站点默认跟随系统外观，也可通过右上角切换按钮手动切换，无需额外配置。
如何部署到自己的服务器？
将 npm run docs:build 产出的 docs/.vitepress/dist 目录托管到任意静态服务器（Nginx、对象存储等）即可。详见部署发布。
如何给文档添加多版本切换？
VitePress 官方文档的版本化方案是通过多份静态构建 + 自定义导航实现，也可借助社区插件（如 vitepress-versioning）快速集成。
遇到构建报错怎么办？
常见排查步骤：
- 检查 Node 版本是否为 18 及以上：
node -v； - 删除缓存后重新构建：
rm -rf docs/.vitepress/cache docs/.vitepress/dist； - 重新安装依赖：
rm -rf node_modules && npm install； - 查看完整错误堆栈定位具体文件。
如何自定义页脚？
修改 docs/.vitepress/config.mjs 中 themeConfig.footer 的 message 与 copyright 字段。