组件类

defineNuxtComponent

使用 Options API 定义 Nuxt 组件（不推荐，推荐 <script setup>）。

function defineNuxtComponent(
  options: {
    name?: string
    props?: any
    setup?: (props: any) => any
    // ...其他 Vue Options API 选项
  }
): Component

export default defineNuxtComponent({
  props: {
    title: { type: String, required: true },
    count: { type: Number, default: 0 },
  },
  setup(props) {
    const doubled = computed(() => props.count * 2)
    return { doubled }
  },
  template: '<div>{{ title }}: {{ doubled }}</div>',
})

INFO

️ 仅在必须使用 Options API 时（如迁移旧项目）使用 新项目推荐 <script setup> 语法，自动支持 Nuxt 的自动导入

defineLazyHydrationComponent

定义延迟 Hydration 的组件，用于优化首屏性能。

function defineLazyHydrationComponent(
  options: {
    setup: () => any
    render: () => VNode
    hydrateOn?: 'idle' | 'visible' | 'interaction' | 'media'
    hydrateWhen?: () => boolean
  }
): Component

// 空闲时 Hydration
const LazyChart = defineLazyHydrationComponent({
  setup() {
    const data = ref([])
    return { data }
  },
  render() {
    return h('div', JSON.stringify(this.data))
  },
  hydrateOn: 'idle',
})

// 可见时 Hydration
const LazyMap = defineLazyHydrationComponent({
  setup() {
    const center = ref([39.9, 116.4])
    return { center }
  },
  render() {
    return h('div', { class: 'map' }, 'Map: ' + this.center)
  },
  hydrateOn: 'visible',
})

TIP

这是 Nuxt 4 的实验性特性 需在 nuxt.config.ts 中启用 experimental.lazyHydration

prefetchComponents

预取组件（后台加载但不渲染），适合在用户可能访问的页面前提前加载。

function prefetchComponents(
  names: string | string[] // 组件名称（PascalCase）
): void

prefetchComponents('MyHeavyComponent')
prefetchComponents(['ChartComponent', 'MapComponent'])

使用场景

// 在用户悬停导航时预取目标页面的组件
function onNavHover() {
  prefetchComponents('DashboardCharts')
}

TIP

预取是低优先级的 不会阻塞当前页面的渲染。组件名称必须与文件名匹配（PascalCase）

preloadComponents

预加载组件（高优先级，立即加载），适合关键路径上的组件。

function preloadComponents(
  names: string | string[] // 组件名称（PascalCase）
): Promise<void>

preloadComponents('CriticalComponent')
preloadComponents(['HeaderComponent', 'NavComponent'])

// 等待加载完成
await preloadComponents('EssentialWidget')

prefetch vs preload

特性	prefetchComponents	preloadComponents
优先级	低（空闲时加载）	高（立即加载）
是否阻塞	不阻塞渲染	可能影响性能
返回值	void	Promise<void>
适用场景	可能需要的组件	即将使用的组件

INFO

️ 在大多数情况下 Nuxt 的自动代码分割已经足够，无需手动预加载。仅在性能分析发现具体瓶颈时使用