Nuxt3 → Nuxt4 完整迁移手册

迁移前评估：
- [ ] 当前 Nuxt 版本：_____（建议先升级到 Nuxt 3.15+）
- [ ] 项目页面数量：_____ 
- [ ] 第三方模块数量：_____（逐一检查 Nuxt4 兼容性）
- [ ] 是否使用 Options API：_____（需要迁移到 Composition API）
- [ ] TypeScript strict 模式：_____（Nuxt4 默认开启）
- [ ] CI/CD 测试覆盖率：_____（建议 > 60% 再迁移）
- [ ] 预计迁移时间：小型项目 1-2 天，大型项目 1-2 周

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

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 3,  // 保持 v3 行为
  },
  experimental: {
    // 逐项开启 v4 特性
    scanPageMeta: true,
    sharedPrerenderData: true,
    compileTemplate: true,
    templateUtils: true,
    defaults: {
      useAsyncData: { deep: false },
    },
  },
})

npx nuxi@latest upgrade --dedupe
npx @nuxt/codemods@latest <codemod-name> <path>

#!/bin/bash
# migrate-to-nuxt4.sh
 
# 1. 创建 app 目录
mkdir -p app
 
# 2. 移动前端目录
for dir in components composables layouts middleware pages plugins utils assets; do
  if [ -d "$dir" ]; then
    mv "$dir" app/
    echo "Moved $dir → app/$dir"
  fi
done
 
# 3. 移动入口文件
for file in app.vue error.vue app.config.ts; do
  if [ -f "$file" ]; then
    mv "$file" app/
    echo "Moved $file → app/$file"
  fi
done
 
# 4. 创建 shared 目录（前后端共享类型/工具）
mkdir -p shared/types shared/utils
 
echo "Migration complete. Run 'pnpm dev' to verify."

// nuxt.config.ts — 新的别名映射
export default defineNuxtConfig({
  alias: {
    '~': './app',
    '@': './app',
    '~~': './',
    '@@': './',
  },
})

// tsconfig.json
{
  "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    "strict": true,  // Nuxt4 默认 strict
    "paths": {
      "~/*": ["./app/*"],
      "@/*": ["./app/*"],
      "~~/*": ["./*"],
      "@@/*": ["./*"],
      "#shared/*": ["./shared/*"]
    }
  }
}

// Nuxt 3 行为：data 是 deep reactive
const { data } = await useFetch('/api/videos')
data.value.items[0].title = 'new title'  // ✅ 自动触发重渲染
 
// Nuxt 4 行为：data 是 shallow reactive
const { data } = await useFetch('/api/videos')
data.value.items[0].title = 'new title'  // ❌ 不会触发重渲染
 
// 修复方式 1：显式设置 deep
const { data } = await useFetch('/api/videos', { deep: true })
 
// 修复方式 2（推荐）：替换整个 data
data.value = { ...data.value, items: updatedItems }

// shared/types/index.ts — 前后端共享类型
export interface Video {
  id: string
  title: string
  description: string
  createdAt: string
}
 
export interface ApiResponse<T> {
  data: T
  meta?: { total: number; page: number }
}

// shared/utils/format.ts — 前后端共享工具
export function formatDuration(seconds: number): string {
  const m = Math.floor(seconds / 60)
  const s = seconds % 60
  return `${m}:${s.toString().padStart(2, '0')}`
}

import type { Video } from '#shared/types'
import { formatDuration } from '#shared/utils/format'

// ❌ 移除：useHead() 的 object syntax 中 hid 属性
useHead({ meta: [{ hid: 'description', name: 'description', content: '...' }] })
 
// ✅ Nuxt4：直接用 name 去重（自动处理）
useHead({ meta: [{ name: 'description', content: '...' }] })

// ❌ 移除：definePageMeta 中 keepalive 字符串
definePageMeta({ keepalive: 'my-page' })
 
// ✅ Nuxt4：使用布尔值或对象
definePageMeta({ keepalive: true })

// ❌ Nuxt3：getQuery 返回的类型可能不准确
const query = getQuery(event)
 
// ✅ Nuxt4：推荐使用 getValidatedQuery 配合 Zod
import { z } from 'zod'
const schema = z.object({ page: z.coerce.number().default(1) })
const query = await getValidatedQuery(event, schema.parse)

# 检查所有已安装模块的 Nuxt4 兼容性
npx nuxi module search --compatibility 4

// 临时降级：对不兼容的模块保持 v3 行为
export default defineNuxtConfig({
  future: { compatibilityVersion: 4 },
  // 但某些模块路径还在旧位置
  modules: ['@some/legacy-module'],
  // 手动配置兼容路径
  alias: {
    '@some/legacy-module': '@some/legacy-module/dist/nuxt3-compat',
  },
})

功能验证：
- [ ] 所有页面可正常访问（SSR + CSR）
- [ ] 页面导航正常（NuxtLink + 编程式导航）
- [ ] 数据获取正常（useFetch / useAsyncData）
- [ ] 表单提交正常
- [ ] 认证流程正常（登录 / 登出 / 权限）
- [ ] 错误页面正常（404 / 500 / error.vue）
 
构建验证：
- [ ] `pnpm dev` 启动无错误
- [ ] `pnpm build` 构建成功
- [ ] `pnpm typecheck` 无类型错误
- [ ] `pnpm lint` 无规范错误
- [ ] `pnpm test` 所有测试通过
 
性能验证：
- [ ] Lighthouse 分数不低于迁移前
- [ ] Bundle 大小不超过迁移前 10%
- [ ] SSR 响应时间无明显增长

// tests/e2e/migration.spec.ts
import { test, expect } from '@playwright/test'
 
test.describe('Post-migration sanity checks', () => {
  test('homepage renders', async ({ page }) => {
    await page.goto('/')
    await expect(page.locator('h1')).toBeVisible()
  })
 
  test('navigation works', async ({ page }) => {
    await page.goto('/')
    await page.click('a[href="/about"]')
    await expect(page).toHaveURL('/about')
  })
 
  test('API routes respond', async ({ request }) => {
    const response = await request.get('/api/health')
    expect(response.ok()).toBe(true)
  })
 
  test('SSR data fetching works', async ({ page }) => {
    await page.goto('/videos')
    const content = await page.textContent('body')
    expect(content).not.toContain('undefined')
    expect(content).not.toContain('null')
  })
 
  test('auth flow works', async ({ page }) => {
    await page.goto('/login')
    await page.fill('input[name="email"]', '[email protected]')
    await page.fill('input[name="password"]', 'password')
    await page.click('button[type="submit"]')
    await expect(page).toHaveURL('/dashboard')
  })
})

// 如果遇到严重问题，可以快速回滚
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 3,  // 回退到 v3 行为
  },
})