feat(@142vip/vitepress): 对依赖进行小版本升级，优化组件导入方式，支持sass高版本编译

Author: mmdapl

packages/vitepress/package.json

@@ -70,30 +70,30 @@
   "peerDependencies": {
     "@142vip/cdn": "0.0.1-alpha.0",
     "@142vip/open-source": "workspace:*",
-    "element-plus": "2.9.7",
-    "mermaid": "11.12.0",
+    "element-plus": "2.13.1",
+    "mermaid": "11.16.0",
     "vitepress": "1.6.4",
-    "vue": "3.5.22"
+    "vue": "3.5.40"
   },
   "dependencies": {
     "@142vip/cdn": "0.0.1-alpha.0",
     "@142vip/open-source": "workspace:*",
     "copy-to-clipboard": "4.0.2",
-    "element-plus": "2.9.7",
-    "mermaid": "11.12.0",
+    "element-plus": "2.13.1",
+    "mermaid": "11.16.0",
     "vitepress": "1.6.4",
-    "vue": "3.5.22"
+    "vue": "3.5.40"
   },
   "devDependencies": {
     "mkdist": "2.4.1",
-    "sass": "1.99.0",
-    "typedoc": "0.28.12",
+    "sass": "1.102.0",
+    "typedoc": "0.28.20",
     "typedoc-github-wiki-theme": "2.1.0",
-    "typedoc-plugin-frontmatter": "1.3.0",
-    "typedoc-plugin-markdown": "4.9.0",
+    "typedoc-plugin-frontmatter": "1.3.1",
+    "typedoc-plugin-markdown": "4.12.0",
     "typedoc-plugin-remark": "2.0.1",
-    "typedoc-vitepress-theme": "1.1.2",
-    "unplugin-element-plus": "0.11.1",
-    "vue-sfc-transformer": "0.1.14"
+    "typedoc-vitepress-theme": "1.1.3",
+    "unplugin-element-plus": "0.11.2",
+    "vue-sfc-transformer": "0.2.3"
   }
 }

packages/vitepress/src/core/mermaid-vite.ts

@@ -1,24 +1,14 @@
+import type { MarkdownOptions, UserConfig } from 'vitepress'
 import { parseVipMermaidFenceInfo } from './mermaid-theme'
 
-interface MarkdownItLike {
-  renderer: {
-    rules: {
-      fence?: (
-        tokens: Array<{ info: string, content: string }>,
-        idx: number,
-        options: unknown,
-        env: unknown,
-        self: { renderToken: (tokens: unknown, idx: number, options: unknown) => string },
-      ) => string
-    }
-  }
-}
+/** 与 `markdown.config(md)` 回调参数类型保持一致，避免手写精简接口 */
+type MarkdownIt = Parameters<NonNullable<MarkdownOptions['config']>>[0]
 
 /**
  * Markdown-it 插件：```mermaid / ```mmd → <VipMermaid>
  * 需配合主题注册 VipMermaid（defineVipExtendsTheme 已内置）
  */
-export function vipMermaidMarkdown(md: MarkdownItLike): void {
+export function vipMermaidMarkdown(md: MarkdownIt): void {
   const defaultFence = md.renderer.rules.fence?.bind(md.renderer.rules)
 
   md.renderer.rules.fence = (tokens, idx, options, env, self) => {
@@ -39,6 +29,38 @@ export function vipMermaidMarkdown(md: MarkdownItLike): void {
   }
 }
 
+const MERMAID_OPTIMIZE_DEPS = ['mermaid', '@braintree/sanitize-url', 'copy-to-clipboard'] as const
+
+function mergeOptimizeDepsInclude(
+  existing: string | string[] | undefined,
+): string[] {
+  const base = existing == null
+    ? []
+    : Array.isArray(existing)
+      ? [...existing]
+      : [existing]
+
+  for (const dep of MERMAID_OPTIMIZE_DEPS) {
+    if (!base.includes(dep)) {
+      base.push(dep)
+    }
+  }
+  return base
+}
+
+/** 启用 Mermaid 时合并 Vite 预构建配置，修复 sanitize-url 等依赖的 CJS/ESM 互操作问题 */
+export function mergeVipMermaidViteConfig(
+  vite: UserConfig['vite'] = {},
+): NonNullable<UserConfig['vite']> {
+  return {
+    ...vite,
+    optimizeDeps: {
+      ...vite.optimizeDeps,
+      include: mergeOptimizeDepsInclude(vite.optimizeDeps?.include),
+    },
+  }
+}
+
 export type { VipMermaidOptions, VipMermaidTheme } from './mermaid-theme'
 export {
   configureVipMermaid,

packages/vitepress/src/core/mermaid.ts

@@ -0,0 +1,41 @@
+import type { UserConfig } from 'vitepress'
+
+type ViteConfig = NonNullable<UserConfig['vite']>
+
+/**
+ * Sass 现代 API 常量（Vite 5.4+ 支持）。
+ *
+ * @see https://sass-lang.com/documentation/breaking-changes/legacy-js-api/
+ */
+const VIP_SASS_MODERN_API = 'modern' as const
+
+/**
+ * 合并 Sass 相关 Vite 配置，消除 `legacy-js-api` 弃用告警。
+ *
+ * 仅在 `defineVipVitepressConfig(..., { mermaid: true })` 时由框架自动调用；
+ * 用户已在 `css.preprocessorOptions` 中设置 `api` 时保留原值。
+ */
+export function mergeVipSassViteConfig(
+  vite: UserConfig['vite'] = {},
+): ViteConfig {
+  const userScss = vite?.css?.preprocessorOptions?.scss
+  const userSass = vite?.css?.preprocessorOptions?.sass
+
+  return {
+    ...vite,
+    css: {
+      ...vite?.css,
+      preprocessorOptions: {
+        ...vite?.css?.preprocessorOptions,
+        scss: {
+          ...userScss,
+          api: userScss?.api ?? VIP_SASS_MODERN_API,
+        },
+        sass: {
+          ...userSass,
+          api: userSass?.api ?? VIP_SASS_MODERN_API,
+        },
+      },
+    },
+  }
+}

packages/vitepress/src/core/sass-vite.ts

@@ -78,9 +78,10 @@ export const vipTeamMembers = [
 ]
 
 /**
- * 基本包结构
+ * 基本包结构。
+ * `extends Record<string, unknown>` 便于在 `getPackageJSON<T>()` 等泛型场景下访问扩展字段。
  */
-export interface VipPackageJSON {
+export interface VipPackageJSON extends Record<string, unknown> {
   name: string
   version: string
   description: string

packages/vitepress/src/core/vip.ts

@@ -2,9 +2,9 @@ import type { MarkdownOptions, UserConfig } from 'vitepress'
 import type { DefaultTheme } from 'vitepress/types/default-theme'
 import type { VipMermaidOptions } from './mermaid-theme'
 import type { NavbarConfig, SidebarConfig } from './types'
-import { vipMermaidMarkdown } from './mermaid'
+import { mergeVipMermaidViteConfig, vipMermaidMarkdown } from './mermaid'
 import { configureVipMermaid } from './mermaid-theme'
-import { mergeVipMermaidViteConfig } from './mermaid-vite'
+import { mergeVipSassViteConfig } from './sass-vite'
 
 /**
  * defineVipVitepressConfig 可选拓展
@@ -53,7 +53,8 @@ export function defineVipVitepressConfig(
   return {
     ...userConfig,
     markdown: defineVipMarkdownConfig(userConfig.markdown),
-    vite: mergeVipMermaidViteConfig(userConfig.vite),
+    // 增量合并 Vite 配置：Sass 现代 API + Mermaid 依赖预构建（不覆盖用户已显式设置的项）
+    vite: mergeVipMermaidViteConfig(mergeVipSassViteConfig(userConfig.vite)),
   }
 }
 

packages/vitepress/src/core/vitepress.ts

@@ -0,0 +1,15 @@
+/// <reference types="vite/client" />
+
+/** 包内 TypeScript 模块声明（构建工具不生成，需在源码侧补充） */
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+
+  const component: DefineComponent<object, object, unknown>
+  export default component
+}
+
+declare module '@142vip/cdn/media/svg/*.svg' {
+  const src: string
+  export default src
+}

packages/vitepress/src/env.d.ts

@@ -43,12 +43,12 @@ export default function defineVipExtendsTheme(theme?: Theme) {
       })
     },
     enhanceApp: ({ app }: EnhanceAppContext) => {
-      // 按需引入
-      app.component(ElBacktop)
-      app.component(ElImage)
-      app.component(ElTable)
-      app.component(ElTableColumn)
-      app.component(ElTag)
+      // element-plus 2.13+ 的 component() 重载需显式传入组件名
+      app.component('ElBacktop', ElBacktop)
+      app.component('ElImage', ElImage)
+      app.component('ElTable', ElTable)
+      app.component('ElTableColumn', ElTableColumn)
+      app.component('ElTag', ElTag)
       // Mermaid 组件（配合 defineVipVitepressConfig(..., { mermaid: true })）
       app.component('VipMermaid', VipMermaid)
     },

packages/vitepress/src/theme/index.ts

@@ -1,5 +1,13 @@
 {
   "extends": "../../tsconfig.package.json",
+  "compilerOptions": {
+    // typedoc 子路径导出在严格模式下需显式 paths，否则 typecheck 报找不到模块
+    "paths": {
+      "typedoc": [
+        "./node_modules/typedoc/dist/types/index.d.ts"
+      ]
+    }
+  },
   "include": [
     "src/**/*"
   ],