Nuxt4生产优化技能 nuxt-production

---

name: nuxt-production description: | Nuxt 4 生产优化：水合作用、性能、使用Vitest进行测试、 部署到Cloudflare/Vercel/Netlify，以及v4迁移。

使用时机：调试水合作用不匹配、优化性能和Core Web Vitals、 使用Vitest编写测试、部署到Cloudflare Pages/Workers/Vercel/Netlify、 或从Nuxt 3迁移到Nuxt 4。

关键词：水合作用, 水合作用不匹配, ClientOnly, SSR, 性能, 懒加载, 懒水合, Vitest, 测试, 部署, Cloudflare Pages, Cloudflare Workers, Vercel, Netlify, NuxtHub, 迁移, Nuxt 3 到 Nuxt 4 license: MIT metadata: version: 4.0.0 author: Claude Skills Maintainers category: Framework framework: Nuxt framework-version: 4.x last-verified: 2025-12-28

Nuxt 4 生产指南

水合作用、性能、测试、部署和迁移模式。

Nuxt 4 中的新特性

v4.2 特性（最新）

1. 数据获取的中止控制

const controller = ref<AbortController>()

const { data } = await useAsyncData(
  'users',
  () => $fetch('/api/users', { signal: controller.value?.signal })
)

const abortRequest = () => {
  controller.value?.abort()
  controller.value = new AbortController()
}

2. 异步数据处理器提取

• 客户端包大小减少39%
• 数据获取逻辑提取到服务器块
• 自动优化（无需配置）

3. 增强的错误处理

• 双重错误显示：自定义错误页面 + 技术覆盖层
• 开发中更好的错误消息

v4.1 特性

1. 增强的块稳定性

• 导入映射防止级联哈希变化
• 更好的长期缓存

2. 懒水合

<script setup>
const LazyComponent = defineLazyHydrationComponent(() =>
  import('./HeavyComponent.vue')
)
</script>

从v3的破坏性变化

变化	v3	v4
源代码目录	根目录	app/
数据反应性	深度	浅层（默认）
默认值	null	undefined
路由中间件	客户端	服务器
应用清单	可选	默认

何时加载参考

加载 references/hydration.md 当：

• 调试“水合节点不匹配”错误
• 实现ClientOnly组件
• 修复非确定性渲染问题
• 理解SSR与客户端渲染

加载 references/performance.md 当：

• 优化Core Web Vitals分数
• 实现懒加载和代码分割
• 配置缓存策略
• 减少包大小

加载 references/testing-vitest.md 当：

• 使用@nuxt/test-utils编写组件测试
• 使用Nuxt上下文测试可组合项
• 模拟Nuxt API（useFetch, useRoute）
• 设置Vitest配置

加载 references/deployment-cloudflare.md 当：

• 部署到Cloudflare Pages或Workers
• 配置wrangler.toml
• 设置NuxtHub集成
• 使用D1, KV, R2绑定

水合最佳实践

导致水合不匹配的原因

原因	示例	修复
非确定性值	Math.random()	使用 useState
服务器上的浏览器API	window.innerWidth	使用 onMounted
服务器上的日期/时间	new Date()	使用 useState 或 ClientOnly
第三方脚本	分析	使用 ClientOnly

修复模式

非确定性值：

<!-- 错误 -->
<script setup>
const id = Math.random()
</script>

<!-- 正确 -->
<script setup>
const id = useState('random-id', () => Math.random())
</script>

浏览器API：

<!-- 错误 -->
<script setup>
const width = window.innerWidth  // 在服务器上崩溃！
</script>

<!-- 正确 -->
<script setup>
const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})
</script>

ClientOnly组件：

<template>
  <!-- 包裹客户端专用内容 -->
  <ClientOnly>
    <MyMapComponent />
    <template #fallback>
      <div class="skeleton">加载地图中...</div>
    </template>
  </ClientOnly>
</template>

条件渲染：

<script setup>
const showWidget = ref(false)

onMounted(() => {
  // 只在水合后显示
  showWidget.value = true
})
</script>

<template>
  <AnalyticsWidget v-if="showWidget" />
</template>

性能优化

懒加载组件

<script setup>
// 懒加载重型组件
const HeavyChart = defineAsyncComponent(() =>
  import('~/components/HeavyChart.vue')
)

// 带有加载/错误状态
const HeavyChart = defineAsyncComponent({
  loader: () => import('~/components/HeavyChart.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorFallback,
  delay: 200,
  timeout: 10000
})
</script>

<template>
  <Suspense>
    <HeavyChart :data="chartData" />
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

懒水合

<script setup>
// 当在视口中可见时水合
const LazyComponent = defineLazyHydrationComponent(
  () => import('./HeavyComponent.vue'),
  { hydrate: 'visible' }
)

// 在用户交互时水合
const InteractiveComponent = defineLazyHydrationComponent(
  () => import('./InteractiveComponent.vue'),
  { hydrate: 'interaction' }
)

// 当浏览器空闲时水合
const IdleComponent = defineLazyHydrationComponent(
  () => import('./IdleComponent.vue'),
  { hydrate: 'idle' }
)
</script>

路由缓存

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // 静态页面（构建时预渲染）
    '/': { prerender: true },
    '/about': { prerender: true },

    // SWR缓存（1小时）
    '/blog/**': { swr: 3600 },

    // ISR（每小时重新生成）
    '/products/**': { isr: 3600 },

    // SPA模式（无SSR）
    '/dashboard/**': { ssr: false },

    // 带有CDN缓存的静态
    '/static/**': {
      headers: { 'Cache-Control': 'public, max-age=31536000' }
    }
  }
})

图像优化

<template>
  <!-- 使用NuxtImg自动优化 -->
  <NuxtImg
    src="/images/hero.jpg"
    alt="英雄图像"
    width="800"
    height="400"
    loading="lazy"
    placeholder
    format="webp"
  />

  <!-- 响应式图像 -->
  <NuxtPicture
    src="/images/product.jpg"
    alt="产品"
    sizes="sm:100vw md:50vw lg:400px"
    :modifiers="{ quality: 80 }"
  />
</template>

使用Vitest进行测试

设置

bun add -d @nuxt/test-utils vitest @vue/test-utils happy-dom

// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    environmentOptions: {
      nuxt: {
        domEnvironment: 'happy-dom'
      }
    }
  }
})

组件测试

// tests/components/UserCard.test.ts
import { describe, it, expect } from 'vitest'
import { mountSuspended } from '@nuxt/test-utils/runtime'
import UserCard from '~/components/UserCard.vue'

describe('UserCard', () => {
  it('渲染用户姓名', async () => {
    const wrapper = await mountSuspended(UserCard, {
      props: {
        user: { id: 1, name: 'John Doe', email: 'john@example.com' }
      }
    })

    expect(wrapper.text()).toContain('John Doe')
    expect(wrapper.text()).toContain('john@example.com')
  })

  it('触发删除事件', async () => {
    const wrapper = await mountSuspended(UserCard, {
      props: { user: { id: 1, name: 'John' } }
    })

    await wrapper.find('[data-test="delete-btn"]').trigger('click')

    expect(wrapper.emitted('delete')).toHaveLength(1)
    expect(wrapper.emitted('delete')[0]).toEqual([1])
  })
})

模拟可组合项

// tests/components/Dashboard.test.ts
import { describe, it, expect, vi } from 'vitest'
import { mountSuspended, mockNuxtImport } from '@nuxt/test-utils/runtime'
import Dashboard from '~/pages/dashboard.vue'

// 模拟useFetch
mockNuxtImport('useFetch', () => {
  return () => ({
    data: ref({ users: [{ id: 1, name: 'John' }] }),
    pending: ref(false),
    error: ref(null)
  })
})

describe('Dashboard', () => {
  it('显示来自API的用户', async () => {
    const wrapper = await mountSuspended(Dashboard)

    expect(wrapper.text()).toContain('John')
  })
})

测试服务器路由

// tests/api/users.test.ts
import { describe, it, expect } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'

describe('API: /api/users', async () => {
  await setup({ server: true })

  it('返回用户列表', async () => {
    const users = await $fetch('/api/users')

    expect(users).toHaveProperty('users')
    expect(Array.isArray(users.users)).toBe(true)
  })

  it('创建新用户', async () => {
    const result = await $fetch('/api/users', {
      method: 'POST',
      body: { name: 'Jane', email: 'jane@example.com' }
    })

    expect(result.user.name).toBe('Jane')
  })
})

部署

Cloudflare Pages（推荐）

# 构建和部署
bun run build
bunx wrangler pages deploy .output/public

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages'
  }
})

Cloudflare Workers

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-module'
  }
})

# wrangler.toml
name = "my-nuxt-app"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxx-xxx-xxx"

[[kv_namespaces]]
binding = "KV"
id = "xxx-xxx-xxx"

Vercel

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'vercel'
  }
})

Netlify

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'netlify'
  }
})

NuxtHub（Cloudflare 一体化）

bun add @nuxthub/core

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxthub/core'],

  hub: {
    database: true,  // D1
    kv: true,        // KV
    blob: true,      // R2
    cache: true      // Cache API
  }
})

// 在服务器路由中的使用
export default defineEventHandler(async (event) => {
  const db = hubDatabase()
  const kv = hubKV()
  const blob = hubBlob()

  // 像常规Cloudflare绑定一样使用
  const users = await db.prepare('SELECT * FROM users').all()
})

环境变量

# .env（开发）
API_SECRET=dev-secret
DATABASE_URL=http://localhost:8787

# 生产（Cloudflare）
wrangler secret put API_SECRET
wrangler secret put DATABASE_URL

# 生产（Vercel/Netlify）
# 在仪表板或CLI中设置

从Nuxt 3迁移

步骤1：更新package.json

{
  "devDependencies": {
    "nuxt": "^4.0.0"
  }
}

步骤2：启用兼容性模式

// nuxt.config.ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4
  }
})

步骤3：将文件移动到app/

# 创建app目录
mkdir app

# 移动文件
mv components app/
mv composables app/
mv pages app/
mv layouts app/
mv middleware app/
mv plugins app/
mv assets app/
mv app.vue app/
mv error.vue app/

步骤4：修复浅层反应性

// 如果修改data.value属性：
const { data } = await useFetch('/api/user', {
  deep: true  // 启用深度反应性
})

// 或替换整个值
data.value = { ...data.value, name: 'New Name' }

步骤5：更新默认值

// v3: data.value 是 null
// v4: data.value 是 undefined

// 更新null检查
if (data.value === null) // v3
if (!data.value)         // v4（两者都适用）

常见反模式

服务器上的客户端专用代码

// 错误
const width = window.innerWidth

// 正确
if (import.meta.client) {
  const width = window.innerWidth
}

// 或使用onMounted
onMounted(() => {
  const width = window.innerWidth
})

非确定性SSR

// 错误 - 服务器与客户端不同
const id = Math.random()
const time = Date.now()

// 正确 - 使用useState保持一致性
const id = useState('id', () => Math.random())
const time = useState('time', () => Date.now())

异步组件缺少Suspense

<!-- 错误 -->
<AsyncComponent />

<!-- 正确 -->
<Suspense>
  <AsyncComponent />
  <template #fallback>
    <LoadingSpinner />
  </template>
</Suspense>

故障排除

水合不匹配：

• 检查 window、document、localStorage 的使用
• 包裹在 ClientOnly 中或使用 onMounted
• 查找 Math.random()、Date.now()、crypto.randomUUID()

构建错误：

rm -rf .nuxt .output node_modules/.vite && bun install

部署失败：

• 检查 nitro.preset 是否匹配目标
• 验证环境变量是否设置
• 检查wrangler.toml绑定是否匹配代码

测试失败：

• 确保 @nuxt/test-utils 已安装
• 检查vitest.config.ts是否有 environment: 'nuxt'
• 对异步组件使用 mountSuspended

相关技能

• nuxt-core：项目设置、路由、配置
• nuxt-data：可组合项、数据获取、状态
• nuxt-server：服务器路由、API模式
• cloudflare-d1：D1数据库模式

---

版本：4.0.0 | 最后更新：2025-12-28 | 许可证：MIT