从VuePress迁移到VitePressVuePress 和 VitePress 是基于 Vue 的静态站点生成器，它

是什么？

VuePress 和 VitePress 是基于 Vue 的静态站点生成器，它们可以 Markdown 内容并导出高性能的多页站点。

它们的默认主题在设计时考虑了软件留档，但非常适合任何基于章节的主题——想想 Docusaurus、Starlight 等。对于自定义主题，它们是任何静态站点的合理选择。

VuePress 首先出现在 2018 年。

VuePress 稳定版 1. x 经历了大约一年的积极开发。

2020 年底出现了第一个 VuePress v2。那时，VitePress 的工作正在顺利进行当时，预计 VitePress 将作为 VuePress v3 发布。

事实并非如此：两者保持分离。今天，VitePress 得到了 Vue.js 团队的支持，VuePress 得到了社区的支持。

为什么？

VuePress 是我多年来的首选软件留档框架。自从 VitePress 在撰写本文前六个月发布最初的稳定版本以来，我一直在将 VuePress 站点迁移到 VitePress。

VitePress 文档状态

VitePress 是 VuePress 的精神继承者… VitePress 提供了明显更好的 DX、更好的生产性能、更精致的默认主题和更灵活的定制应用编程接口。

对我来说，一个主要的好处是网站搜索。

VuePress 支持自己的搜索，但这可能会很慢。 VuePress 还支持使用 Algolia 的 DocSearch 或标准 Algolia。DocSearch 团队只批准“公开可用的开发人员留档或技术博客”的网站。

VitePress 对迷你搜索有开箱即用的支持。启用它只需要一行代码，更新网站内容时不需要额外的工作。这比我在 VuePress 中使用标准 Algolia 所做的有了巨大的改进。（在VitePress 的本地搜索文档中阅读更多）

怎么做？

这些是我采取的步骤：

删除特定于 VuePress 的依赖项，包括@vuepress范围内的任何内容。

pnpm remove vue vuepress # and possibly `@vuepress/bundler-vite`, `@vuepress/theme-default`, "`@vuepress/plugin-blog`, etc.

添加 VitePress 依赖项

pnpm add -D vitepress

初始化 VitePress。

当询问您是否要添加包脚本时，选择是。

如果您自定义了 VuePress 站点（例如，使用vuepress/styles/index.scss），当询问您是否要自定义主题时，请选择“默认主题+自定义”。

bun vitepress init# ornpx vitepress init # N.B: not `npm`# orpnpm vitepress init# oryarn vitepress init

如果您使用“默认主题+自定义”初始化 VitePress，请安装vue：

pnpm add -D vue

删除 VitePress 的示例 Markdown 文件

rm api-examples.md markdown-examples.md

并从. vitepress/config.（js|ts）中删除对api-examples.md和markdown-examples.md``.vitepress/config.(js|ts)。

注释掉引用在.vitepress/theme/index.(js|ts)到style.css。
更新.gitignore

VuePress 的缓存目录是点前缀的。VitePress 不是。VitePress 没有temp目录。更改将类似于

.vuepress/.temp.vuepress/.cache.vuepress/dist.vitepress/cache.vitepress/dist

将public目录移动到 docs 根目录

mv .vuepress/public public

删除 VuePress 工件

rm -rf .vuepress/.cache .vuepress/.temp .vuepress/dist

移动 CSS 文件。⚠️ 请注意，VitePress 会自动发现它们。稍后再谈。

mv .vuepress/styles/* .vitepress/theme

将组件等从.vuepress移动到.vitepress。例如，这可能看起来像

mv .vitepress/components .vuepress/componentsmv .vitepress/stores .vuepress/storesmv .vitepress/utilities .vuepress/utilities

迁移.vuepress/client.(js|ts)的内容到.vitepress/theme/index.(js|ts)。例如，将@vuepress/client的defineClientConfig.enhance中的所有内容移动到 VitePress 主题的enhanceApp，如下所示

vuepress/client.tsts

import { defineClientConfig } from '@vuepress/client';
import MyComponent from './components/MyComponent.vue';

export default defineClientConfig({
  enhance({ app }) {
    // …
    app.component('MyComponent', MyComponent);
    // …
  },
});

会变成这样

// …
import MyComponent from '../components/MyComponent.vue';
export default {
  // …
  enhanceApp({ app }) {
    // …
    app.component('MyComponent', MyComponent);
    // …
  },
  // …
};

迁移配置。有些东西是一样的，有些是不同的。

VuePress 文档：VuePress 站点配置，VuePress 主题配置

VitePress 文档：VitePress 站点配置，VitePress 主题配置

我遇到的陷阱：

VuePress 的markdown.links.externalAttrs是 VitePress 的markdown.externalLinks。
在 VuePress 中，为了防止 Markdown 中的外部链接在新选项卡中打开

// …
markdown: {
  links: {
    externalAttrs: {
      target: '',
    },
  },
},
// …

在 VitePress 中

// …
markdown: {
  externalLinks: {
    target: '_self',
  },
},
// …

VuePress 的themeConfig.navbar是 VitePress 的themeConfig.nav。
VuePress 的themeConfig.sidebar支持 URL 字符串和从文件内容中插入项目文本，如下所示

// …
sidebar: [
  // …
  'file.md',
  // …
],
// …

VitePress 的链接侧边栏项必须是带有link和显式text的对象，如下所示：

// …
sidebar: [
  // …
  {
    link: 'file.md',
    text: 'The File',
  },
  // …
],
// …

VuePress 的主题themeConfig.sidebar组在children项下。VuePress 的在items下。

启动开发模式：

pnpm run docs:dev

处理任何剩余的.vuepress文件。
删除.vuepress目录。
如果您将任何样式表移动到.vitepress，
- 将 SCSS 移植到 CSS，并重命名文件以使用扩展名css而不是scss。
- 将它们导入.vitepress/theme/index.(js|ts)：
```
import './<the file name>.css';
```
- 参考.vitepress/theme/style.css并在浏览器中检查，找出您想在 VitePress 中使用的自定义 VuePress 样式，以及如何应用它们。
删除 VitePress 的示例 CSS

rm .vitepress/theme/style.css