API 参考

vitepress-tuck

defineConfig

defineConfig 是 vitepress-tuck 的核心函数，用于替代 VitePress 的 defineConfig。

import { defineConfig } from 'vitepress-tuck'

function defineConfig<ThemeConfig = DefaultTheme.Config>(
  config: UserConfig<NoInfer<ThemeConfig>> & TuckConfig,
): UserConfig<NoInfer<ThemeConfig>>

参数

参数	类型	说明
config	UserConfig & TuckConfig	VitePress 原始配置 + plugins 选项

TuckConfig 定义：

interface TuckConfig {
  /**
   * vitepress 插件列表
   */
  plugins?: VitepressPlugin[]

  /**
   * unplugin-vue-components 插件选项
   *
   * @see - https://github.com/unplugin/unplugin-vue-components
   */
  components?: ComponentsOptions
}

返回值

返回合并后的完整 VitePress 配置对象 UserConfig。

工作原理

1. 遍历 plugins 数组，合并每个插件的 markdown、vite、vue 等配置
2. 收集所有钩子函数（buildEnd、transformHead、transformHtml、transformPageData、postRender），并按照各自的策略合并：
   • markdown.config、buildEnd → 并发执行
   • transformHead → 并发执行后合并结果
   • transformHtml、transformPageData、postRender → 顺序执行，链式传递
3. 将插件中的 client 配置注入到内置的 virtual-enhance-app 虚拟模块
4. 将插件中的 componentResolver 收集到内置的 unplugin-vue-components 解析器列表
5. 最后合并用户自身的配置项

---

definePlugin

用于定义 VitePress 插件。它是一个类型辅助函数，帮助开发者以规范化的方式创建插件。

import { definePlugin } from 'vitepress-tuck'

function definePlugin<T>(
  plugin: (option?: T) => VitepressPlugin,
): (option?: T) => VitepressPlugin

参数

参数	类型	说明
plugin	(option?: T) => VitepressPlugin	插件工厂函数，接收可选配置项，返回插件对象

---

VitepressPlugin

插件对象的类型定义：

interface VitepressPlugin extends Pick<
  UserConfig,
  'markdown' | 'vite' | 'vue' | 'buildEnd' | 'transformHead' | 'transformHtml' | 'transformPageData' | 'postRender'
> {
  /**
   * 插件名称（必填，用于标识和调试）
   */
  name: string

  /**
   * 客户端配置，用于自动注入到 virtual:enhance-app
   */
  client?: {
    /**
     * 自定义的 import 语句列表
     *
     * @example
     * ```ts
     * imports: ['import "my-plugin/style.css"']
     * ```
     */
    imports?: string[]

    /**
     * 客户端增强函数名。
     * - 未设置: 不注入 enhanceApp 函数
     * - true: 默认函数名为 `enhanceApp`
     * - 字符串: 指定函数名
     *
     * @example
     * ```ts
     * enhance: 'enhanceAppWithMyPlugin'
     * ```
     */
    enhance?: string | boolean
  }

  /**
   * 组件解析器，用于 unplugin-vue-components 自动按需导入。
   *
   * - 字符串数组：声明的组件名将从 `<插件名>/client` 自动解析
   * - ComponentResolver 对象：自定义解析逻辑
   *
   * @example
   * ```ts
   * // 简单形式
   * componentResolver: ['MyComponent', 'OtherComponent']
   * ```
   */
  componentResolver?: string[] | ComponentResolver
}

支持的 VitePress 配置项

属性	类型	说明
markdown	UserConfig['markdown']	Markdown 相关配置，常用于 markdown.config 注册 markdown-it 插件
vite	UserConfig['vite']	Vite 配置，用于注册 Vite 插件和优化配置
vue	UserConfig['vue']	Vue 应用级别的配置
buildEnd	UserConfig['buildEnd']	构建完成钩子（并发执行）
transformHead	UserConfig['transformHead']	转换 HTML 头部钩子（并发执行，合并结果）
transformHtml	UserConfig['transformHtml']	转换 HTML 钩子（顺序执行，链式传递）
transformPageData	UserConfig['transformPageData']	转换页面数据钩子（顺序执行，链式传递）
postRender	UserConfig['postRender']	页面渲染后钩子（顺序执行，链式传递）

---

virtual:enhance-app

virtual:enhance-app 是一个虚拟模块，由 vitepress-tuck 内置提供。它自动收集所有插件的 client 配置并生成对应的代码。

使用时在主题入口中导入：

.vitepress/theme/index.ts

import enhanceApp from 'virtual:enhance-app'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceApp(ctx)
  },
}

TypeScript 类型支持需要添加类型引用：

tsconfig.json

{
  "compilerOptions": {
    "types": ["vitepress-tuck/client-types"]
  }
}

---

内置插件：auto-components

vitepress-tuck 内置集成了 unplugin-vue-components 插件，提供自动按需组件导入能力。该插件作为内置插件自动启用，无需手动注册。

默认行为

• 扫描 .vue 和 .md 文件中的组件使用
• 类型声明文件生成到 node_modules/.vite/components.d.ts
• 自动收集所有插件的 componentResolver 声明

自定义配置

通过 defineConfig 的 components 选项可以自定义 unplugin-vue-components 的行为：

import { defineConfig } from 'vitepress-tuck'

export default defineConfig({
  components: {
    // 自定义扫描目录
    dirs: ['src/components'],
    // 目录作为命名空间
    directoryAsNamespace: true,
    // 其他 unplugin-vue-components 选项...
  },
  plugins: [],
})

TIP

插件的 componentResolver 声明会与用户在 components 中的配置合并。插件开发者只需在插件中声明 componentResolver，用户即可直接在 Markdown 或 Vue 文件中使用对应组件，无需手动 import。