Nuxt4 常见坑点与解决方案

<template>
  <!-- 方案 1：ClientOnly 包裹（简单但影响 SEO） -->
  <ClientOnly>
    <span>{{ timeAgo(video.createdAt) }}</span>
    <template #fallback>
      <span>{{ formatDate(video.createdAt) }}</span>
    </template>
  </ClientOnly>
 
  <!-- 方案 2：用固定格式代替相对时间（推荐） -->
  <time :datetime="video.createdAt">{{ formatDate(video.createdAt, 'YYYY-MM-DD') }}</time>
</template>

<script setup lang="ts">
// ❌ 直接访问浏览器 API
const theme = localStorage.getItem('theme')
 
// ✅ 方案 1：import.meta.client 守卫
let theme = 'light'
if (import.meta.client) {
  theme = localStorage.getItem('theme') ?? 'light'
}
 
// ✅ 方案 2：onMounted 中访问
onMounted(() => {
  const theme = localStorage.getItem('theme')
})
 
// ✅ 方案 3：.client.vue 组件后缀
// 把依赖浏览器 API 的逻辑放到 ThemeToggle.client.vue
</script>

<script setup lang="ts">
// ❌ 每次执行结果不同
const id = Math.random().toString(36).slice(2)
 
// ✅ 使用 useId()（Nuxt 内置，SSR 安全）
const id = useId()
</script>

<template>
  <!-- ❌ SSR 时没有 window.innerWidth -->
  <MobileNav v-if="isMobile" />
 
  <!-- ✅ 用 CSS 隐藏代替 v-if -->
  <MobileNav class="md:hidden" />
  <DesktopNav class="hidden md:block" />
 
  <!-- ✅ 或用 ClientOnly -->
  <ClientOnly>
    <MobileNav v-if="isMobile" />
  </ClientOnly>
</template>

// nuxt.config.ts — 方案 1：在 Vite 配置中排除 SSR
export default defineNuxtConfig({
  vite: {
    optimizeDeps: {
      include: ['chart.js'],
    },
  },
  // 将库标记为仅客户端
  build: {
    transpile: ['chart.js'],
  },
})

<!-- 方案 2：动态导入 + .client.vue -->
<!-- components/Chart.client.vue -->
<script setup lang="ts">
const { Chart } = await import('chart.js')
// 这里可以安全使用 Chart.js
</script>

// 方案 3：插件中标记 client-only
// plugins/chart.client.ts（注意 .client 后缀）
import { Chart } from 'chart.js'
export default defineNuxtPlugin(() => {
  return { provide: { Chart } }
})

# 检查模块兼容性
npx nuxi module search @nuxtjs/xxx
 
# 查看已安装模块的状态
npx nuxi info

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  // ✅ 使用 useState 而不是 ref，确保 SSR → CSR 同步
  const user = useState<User | null>('user', () => null)
  const isLoggedIn = computed(() => !!user.value)
 
  return { user, isLoggedIn }
})

# 重新生成类型
rm -rf .nuxt
npx nuxi prepare
 
# 如果还不行，清除 node_modules
rm -rf node_modules .nuxt
pnpm install
npx nuxi prepare

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/video/1', '/video/2'],
      // 或自动爬取
      crawlLinks: true,
    },
  },
})

// 或在 server/api/ 提供路由列表
// server/routes/sitemap.xml.ts
export default defineEventHandler(async () => {
  const videos = await db.select({ id: videosTable.id }).from(videosTable)
  // ...生成 sitemap
})

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" npx nuxi build
 
# 或在 package.json 中配置
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' nuxi build"
  }
}

# 核弹选项：清除所有缓存
rm -rf .nuxt .output node_modules/.cache
pnpm dev

// 方案 1：确保 API 路由有明确的返回类型
// server/api/videos.get.ts
export default defineEventHandler(async (): Promise<Video[]> => {
  return db.select().from(videosTable)
})
 
// 方案 2：在 useFetch 中指定泛型
const { data } = await useFetch<{ items: Video[], total: number }>('/api/videos')

# 方案 3：重新生成类型
npx nuxi prepare

// 使用 typed pages（Nuxt 实验特性）
export default defineNuxtConfig({
  experimental: {
    typedPages: true,
  },
})
 
// 使用后 route.params 自动有正确类型

// ❌ 隐式返回（模板可能丢失类型）
export function useVideo(id: string) {
  const data = ref<Video | null>(null)
  return { data }
}
 
// ✅ 显式接口（模板类型完整）
interface UseVideoReturn {
  data: Ref<Video | null>
  loading: Ref<boolean>
  refresh: () => Promise<void>
}
 
export function useVideo(id: string): UseVideoReturn {
  // ...
}

<script setup lang="ts">
// ❌ N 次请求
const items = ref([])
for (const id of ids) {
  const { data } = await useFetch(`/api/videos/${id}`)
  items.value.push(data.value)
}
 
// ✅ 一次请求，批量获取
const { data: items } = await useFetch('/api/videos', {
  query: { ids: ids.join(',') },
})
</script>

// 使用 transform 只保留需要的字段
const { data } = await useFetch('/api/videos', {
  transform: (res) => res.items.map(v => ({
    id: v.id,
    title: v.title,
    thumbnail: v.thumbnail,
    // 不传递 description、tags、metadata 等大字段
  })),
})

// 或使用 pick（选择要传递的顶层字段）
const { data } = await useFetch('/api/video/123', {
  pick: ['id', 'title', 'thumbnail', 'duration'],
})

<script setup lang="ts">
// ✅ onMounted + onUnmounted 配对
let timer: ReturnType<typeof setInterval>
 
onMounted(() => {
  timer = setInterval(() => {
    refreshData()
  }, 30_000)
})
 
onUnmounted(() => {
  clearInterval(timer)
})
 
// ✅ 或使用 VueUse 的 useIntervalFn（自动清理）
const { pause, resume } = useIntervalFn(refreshData, 30_000)
</script>

<script setup lang="ts">
// ❌ 同步导入（打进主 bundle）
import HeavyEditor from '~/components/HeavyEditor.vue'
 
// ✅ 懒加载（独立 chunk）
const HeavyEditor = defineAsyncComponent(
  () => import('~/components/HeavyEditor.vue')
)
</script>
 
<!-- ✅ 或使用 Lazy 前缀（Nuxt 自动转为异步组件） -->
<template>
  <LazyHeavyEditor v-if="showEditor" />
</template>

export default defineNuxtConfig({
  runtimeConfig: {
    // ✅ 声明了默认值，运行时从 NUXT_DB_URL 读取
    dbUrl: 'postgresql://localhost/dev',
    public: {
      // ✅ 声明了默认值，运行时从 NUXT_PUBLIC_API_BASE 读取
      apiBase: 'http://localhost:3000',
    },
  },
})

// package.json
{
  "engines": {
    "node": ">=20.0.0"
  }
}

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    baseURL: '/app/',
  },
})