Nuxt.js 官网开发常见问题

在使用 Nuxt.js 开发企业官网时，经常会遇到各种各样的问题。作为一个基于 Vue.js 的服务端渲染框架，Nuxt.js 在提供 SEO 友好、性能优化等方面有很大优势，但同时也带来了一些开发挑战。

1. 服务端渲染与客户端渲染混用导致的问题

问题描述：在 Nuxt 项目中混用<client-only>和服务端组件，导致水合(hydration)不匹配错误。

<template>
  <div>
    <h1>{{ serverData }}</h1>
    <client-only>
      <ComplexComponent :data="clientData" />
    </client-only>
  </div>
</template>

<script setup>
const serverData = ref("服务端数据");
// 这里的数据在服务端和客户端可能不同步
const clientData = ref(null);

onMounted(() => {
  clientData.value = window.localStorage.getItem("userData");
});
</script>

解决方案：

确保客户端专用组件不依赖服务端渲染的数据
使用useNuxtApp()的$router.isReady来确保在路由准备好后再加载客户端数据
对于 localStorage 等浏览器 API，使用适当的生命周期钩子:

<script setup>
const clientData = ref(null);

// 正确方式
onMounted(() => {
  setTimeout(() => {
    clientData.value = JSON.parse(localStorage.getItem("userData") || "null");
  }, 0);
});
</script>

2. 图片优化和静态资源处理

问题描述：官网通常有大量图片和静态资源，未经优化会导致加载性能差。

解决方案：

使用 Nuxt 的内置图片优化模块@nuxt/image：

npm install --save-dev @nuxt/image

<template>
  <nuxt-img
    src="/banner.png"
    formats="webp"
    width="1200"
    height="600"
    loading="lazy"
    placeholder
  />
</template>

静态资源添加版本号和 CDN 配置：

// nuxt.config.js
export default defineNuxtConfig({
  app: {
    baseURL: "/",
    cdnURL: process.env.NODE_ENV === "production" ? "https://your-cdn.com" : "",
    buildAssetsDir: `_assets/${+new Date()}/`, // 添加时间戳避免缓存
  },
});

3. SEO 优化与元数据管理

问题描述：官网 SEO 是核心需求，但动态页面元数据管理复杂。

解决方案：使用 Nuxt 的useHead和useSeoMeta函数:

<script setup>
const route = useRoute();
const { data: pageData } = await useFetch(`/api/pages/${route.params.slug}`);

useSeoMeta({
  title: () => pageData.value?.title || "默认标题",
  description: () => pageData.value?.description || "默认描述",
  ogImage: () => pageData.value?.image || "/default-og.jpg",
});
</script>

4. 国际化实现踩坑

问题描述：多语言官网处理语言切换、路由匹配和 SEO 时遇到的冲突问题。

解决方案：使用@nuxtjs/i18n模块并正确配置：

// nuxt.config.js
modules: [
  '@nuxtjs/i18n',
],

i18n: {
  strategy: 'prefix_except_default',
  defaultLocale: 'zh',
  detectBrowserLanguage: {
    useCookie: true,
    cookieKey: 'i18n_lang',
    redirectOn: 'root', // 只在根路径重定向
  },
  locales: [
    { code: 'zh', iso: 'zh-CN', file: 'zh.json' },
    { code: 'en', iso: 'en-US', file: 'en.json' }
  ],
  vueI18n: {
    fallbackLocale: 'zh',
  }
}

5. 服务端 API 调用超时问题

问题描述：在asyncData或fetch中调用外部 API 时出现超时，导致整个页面加载失败。

解决方案：

设置合理的超时时间并提供回退数据：

<script setup>
const { data: posts, error } = await useFetch("/api/posts", {
  timeout: 5000,
  default: () => [],
  catch: (error) => {
    console.error("API调用失败", error);
    return []; // 提供默认空数据
  },
});
</script>

组件级别的错误处理和加载状态：

<template>
  <div>
    <LoadingSpinner v-if="pending" />
    <ErrorComponent v-else-if="error" :error="error" />
    <ContentDisplay v-else :data="data" />
  </div>
</template>