从 v1 升级到 v2

本指南帮助你从 @fuxishi/vitepress-theme v1.x（基于 VitePress 1.x）平滑迁移到 v2.x（基于 VitePress 2.0）。

前置条件

VitePress 升级到 2.0.0-alpha.20 或更高
Node.js >=22（VitePress 2.0.0-alpha.18 起基于 Vite 8，不再支持 Node 18/20）

bash

npm install vitepress@2.0.0-alpha.20

破坏性变更

1. 配置 API 更新

v2 使用 defineConfig<ThemeConfig>() 替代已废弃的 defineConfigWithTheme，并通过交叉类型组合自定义配置。

v1 写法（已废弃）：

import { defineConfigWithTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeConfig } from "@fuxishi/vitepress-theme/config"

export default defineConfigWithTheme<FxThemeConfig>({
  extends: fxConfig,
  // ...
})

v2 写法：

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  // ...
})

主要变化：

项目	v1	v2
配置函数	`defineConfigWithTheme`	`defineConfig<ThemeConfig>()`
类型导入	`FxThemeConfig` from `.../config`	`FxThemeCustomConfig` from `@fuxishi/vitepress-theme`
类型组合	直接继承 `DefaultTheme.Config`	`DefaultTheme.Config & FxThemeCustomConfig`
额外导入	无	需导入 `DefaultTheme`

2. 主题注册（无变化）

主题注册方式不变：

import FxTheme from "@fuxishi/vitepress-theme"
import "@fuxishi/vitepress-theme/style.css"

export default FxTheme

3. 代码块光束边框增强

v2 中暗色模式的代码块光束边框效果现在也支持代码组（::: code-group）整体容器，hover 时整个代码组展示光束旋转边框。

4. VitePress 2.0 alpha 自身的破坏性变更

主题跟随的 VitePress 2.0.0-alpha.18+ 对上游 API 有以下破坏性调整，如果你的站点用到了这些能力，需要同步修改：

上游变更	处理方式
顶层配置 `scrollOffset` 被移除	通过 CSS 自定义 `scroll-margin-top` 控制锚点滚动偏移
顶层配置 `smoothScroll` 被移除	本主题的 `themeConfig.smoothScroll` 为纯 CSS 实现（且遵循 `prefers-reduced-motion`），不受影响，可继续使用
markdown 选项 `lazyLoading` 更名为 `lazyLoad`	替换配置键名
markdown 废弃项 `cjkFriendly` 移除	CJK 友好断行已成为默认行为，直接删除该配置
themeConfig 废弃项移除：`lastUpdatedText`、`outlineTitle`	分别改用 `lastUpdated.text`、`outline.label`
本地搜索废弃项 `disableDetailedView` 移除	详细视图开关功能已从上游移除
Node 22+ / Vite 8	升级运行时，检查自定义 Vite 插件对 Vite 8 的兼容性

5. 主题层的移除项与破坏性变更（v2.0.0-alpha.20）

移除：导航栏标题溢出 tooltip

VitePress alpha.20 重设计导航栏后，原生支持标题截断（ellipsis）并自带原生 title 提示，主题不再注入 Element Plus 的 ElTooltip，避免与原生提示重复弹出
影响：此前 hover 溢出标题出现的主题样式 tooltip 不再存在，由浏览器原生提示替代；如果你的自定义 CSS 针对导航栏标题 tooltip 写过覆盖样式，可以删除

变更：--vp-code-line-height 改为无单位数值

主题默认值从 2.2em 改为 2.2（与 alpha.20 上游格式对齐）
如果你的自定义 CSS 曾以 em 单位覆盖此变量，必须改为无单位数值（如 1.8），否则代码块折叠的 calc 高度计算会失效
折叠裁剪高度现在按 1lh 单位（元素实际行盒高度）计算，修改行高或代码字号后会自动跟随

变更：代码块折叠裁剪目标从 pre 移至 pre > code

折叠的 max-height / overflow 现在作用于 pre.shiki > code 与行号容器，不再是 pre.shiki
若你曾在自定义 CSS 中覆盖 > pre.shiki 的 max-height 来调整折叠行为，需要同步改为 > pre.shiki > code
横向滚动条由 pre 的 overflow-x: auto 提供（alpha.20 代码本体为 width: fit-content），不要在自定义样式中把 pre 的 overflow 覆盖为 visible，否则长代码行无法横向滚动

移除：Element Plus 依赖

音乐球的进度 / 音量滑块替换为自研 FxSlider 组件（拖动、点击定位、键盘方向键均支持），主题运行时与安装依赖中不再包含 Element Plus
style.css 体积减半（53.7kB → 24.4kB）
如果你曾针对 .fx-music-ball .el-slider 编写过滑块样式覆盖，需改为 .fx-slider / .fx-slider__runway / .fx-slider__bar / .fx-slider__thumb（CSS 变量 --fx-music-slider-track、--fx-music-slider-thumb 等保持不变）

行为变更：平滑滚动遵循系统动画偏好

themeConfig.smoothScroll 开启时，scroll-behavior: smooth 仅在用户未开启"减弱动画"（prefers-reduced-motion: reduce）时生效，这是上游建议的无障碍做法

行为变更：DemoPreview markdown 插件

dir 模式的目录改为相对源文件根目录（包含 .vitepress 的目录）解析，不再依赖启动命令的 cwd
找不到 demo 目录 / 文件时输出控制台警告，不再静默跳过
源码 slot 适配 alpha.19+ 的 snippet 渲染器（token.meta.src）；如果你的项目有自己的 markdown 插件模仿过旧的 token 格式，需要同步修改

迁移步骤

步骤 1：升级依赖

bash

npm install @fuxishi/vitepress-theme@latest
npm install vitepress@latest

步骤 2：更新配置文件

修改 .vitepress/config.mts，按上方 v2 写法 替换配置导入和函数调用。

完整示例：

import { defineConfig } from "vitepress"
import type { DefaultTheme } from "vitepress"
import fxConfig from "@fuxishi/vitepress-theme/config"
import type { FxThemeCustomConfig } from "@fuxishi/vitepress-theme"

type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig

export default defineConfig<ThemeConfig>({
  extends: fxConfig,
  lang: "zh-CN",
  title: "我的文档站",
  themeConfig: {
    // 你原有的配置保持不变
    nav: [{ text: "指南", link: "/guide/" }],
    sidebar: {
      "/guide/": [{ text: "快速开始", link: "/guide/" }],
    },
    // 以下配置项与 v1 完全兼容，无需修改
    musicBall: { enable: true, src: "/music/song.mp3" },
    confetti: true,
    heroImageColor: true,
    smoothScroll: true,
    codeBlockFold: { lines: 10 },
  },
})

步骤 3：验证

启动开发服务器确认一切正常：

bash

npx vitepress dev

无需修改的部分

以下配置和行为在 v2 中完全兼容，无需任何改动：

主题注册 — import FxTheme + import "style.css" 不变
音乐球配置 — musicBall 所有字段不变
彩纸效果配置 — confetti 所有模式不变
Hero 图片取色 — heroImageColor 行为不变
平滑滚动 — smoothScroll 行为不变
代码块折叠 — codeBlockFold 所有字段不变
CSS 变量覆盖 — 所有 --fx-beam-c1、--fx-beam-c2、音乐球变量等不变
自定义 CSS — 所有自定义样式不变

常见问题

TypeScript 报类型错误

确保 tsconfig.json 包含正确的 VitePress 路径配置，并且使用了 type ThemeConfig = DefaultTheme.Config & FxThemeCustomConfig 交叉类型，而不是 FxThemeConfig extends DefaultTheme.Config。

`defineConfigWithTheme` 不存在

VitePress 2.0 已废弃 defineConfigWithTheme，请改用 defineConfig<ThemeConfig>()。

`NoInfer` 报错

NoInfer 是 TypeScript 5.4+ 内置工具类型，不需要从 vitepress 导入。如果遇到此错误，请升级 TypeScript 到 5.4 以上。

从 v1 升级到 v2 ​

前置条件 ​

破坏性变更 ​

1. 配置 API 更新 ​

2. 主题注册（无变化） ​

3. 代码块光束边框增强 ​

4. VitePress 2.0 alpha 自身的破坏性变更 ​

5. 主题层的移除项与破坏性变更（v2.0.0-alpha.20） ​

迁移步骤 ​

步骤 1：升级依赖 ​

步骤 2：更新配置文件 ​

步骤 3：验证 ​

无需修改的部分 ​

常见问题 ​

TypeScript 报类型错误 ​

defineConfigWithTheme 不存在 ​

NoInfer 报错 ​

从 v1 升级到 v2

前置条件

破坏性变更

1. 配置 API 更新

2. 主题注册（无变化）

3. 代码块光束边框增强

4. VitePress 2.0 alpha 自身的破坏性变更

5. 主题层的移除项与破坏性变更（v2.0.0-alpha.20）

迁移步骤

步骤 1：升级依赖

步骤 2：更新配置文件

步骤 3：验证

无需修改的部分

常见问题

TypeScript 报类型错误

`defineConfigWithTheme` 不存在

`NoInfer` 报错