Nuxt 2 迁移至 Nuxt 3 的关键步骤与常见坑点

图 0：Nuxt 2 与 Nuxt 3 核心底层技术架构全景对比

一、迁移前的技术断代评估与环境准备

在 Nuxt 2 的架构中，项目深度绑定了 Vue 2 的选项式 API（Options API）、基于 Object.defineProperty 的响应式系统，以及 Webpack 4 打包链路和 CommonJS 规范。而 Nuxt 3 并非简单的增量补丁，而是基于 Vue 3、Vite/Rollup、Nitro 跨平台引擎以及 ESM 规范的全新全栈框架。因此，迁移的第一要务是明确迁移策略并对齐运行环境。

1. 迁移策略选择：重构迁移 vs Nuxt Bridge

官方曾推出过过渡层工具 Nuxt Bridge，其设计目标是在保留 Nuxt 2 核心的基础上，提前体验 Composition API、Nitro 和 Vite 构建。但在工程实践中需要注意其适用边界：

• Nuxt Bridge 的定位：适合业务体量极大、短期内无法抽调足够资源进行全面重写的历史项目，作为渐进改造的垫脚石。
• Bridge 的局限性：Bridge 依然运行在 Vue 2.7 环境下，无法享受 Vue 3 原生 Proxy 带来的深度性能提升与部分现代 UI 库的最新功能，且往往伴随 Vite 与旧版 Webpack 插件之间的兼容性损耗。
• 推荐路径（直接重构迁移）：对于大多数中小型项目或具备迭代窗口的应用，直接搭建全新的 Nuxt 3 骨架项目，按照模块逐层迁移源码，是工程负担最小、产出架构最纯粹的选择。

2. Node.js 运行环境基准

Nuxt 3 严格依赖现代 Node.js 运行时。开发机与部署服务器必须将 Node.js 升级至 18.0.0 或更高版本（强烈推荐选用当前的 Node.js 20 LTS）。旧版 Node 14 或 16 在解析 ESM 包、Web Streams API 以及 Nitro 原生特性时会直接抛出语法或依赖解析错误。

3. 核心依赖生态兼容性盘查

迁移前应对 package.json 进行逐项审计。许多在 Nuxt 2 中广泛使用的官方或第三方模块不能在 Nuxt 3 中直接沿用，必须替换为对应的新版模块或框架内置方案：

二、标准五步迁移操作指南

在明确了架构差异与依赖选型后，建议按照“基准环境 → 结构配置 → 组件语法 → 全局状态 → 服务端与构建”的标准化流水线有序推进，避免各个模块改动交叉导致的定位混乱。

图 1：Nuxt 2 至 Nuxt 3 标准五步迁移推进流程

步骤一：创建工程骨架与迁移 nuxt.config.ts

首先初始化干净的 Nuxt 3 依赖环境。在根目录下使用 nuxt.config.ts 取代旧版 nuxt.config.js，借助 defineNuxtConfig 获得 IDE 级别的强类型提示。

以下为典型的配置文件改写对照：

// [旧版] nuxt.config.js (Nuxt 2)
export default {
  target: 'server',
  head: {
    title: '我的应用',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' }
    ]
  },
  css: ['~/assets/css/main.css'],
  modules: ['@nuxtjs/axios'],
  env: {
    API_SECRET: process.env.API_SECRET,
    PUBLIC_URL: 'https://api.example.com'
  }
}

改写为符合 Nuxt 3 规范的配置：

// [新版] nuxt.config.ts (Nuxt 3)
export default defineNuxtConfig({
  // target 已废弃，由 Nitro 部署预设自动推断
  app: {
    head: {
      title: '我的应用',
      meta: [
        { charset: 'utf-8' },
        { name: 'viewport', content: 'width=device-width, initial-scale=1' }
      ]
    }
  },
  css: ['~/assets/css/main.css'],
  modules: [
    '@pinia/nuxt' // 移除旧版 axios 模块，接入 pinia
  ],
  runtimeConfig: {
    // 仅在服务端可用（安全性高）
    apiSecret: process.env.NUXT_API_SECRET,
    // 客户端与服务端均可访问
    public: {
      publicUrl: process.env.NUXT_PUBLIC_URL || 'https://api.example.com'
    }
  }
})

步骤二：目录规范与路由重构

Nuxt 3 对目录职责进行了规范化梳理，有几处关键结构调整：

1. 引入顶层 app.vue 入口：Nuxt 3 中 app.vue 是全局首要视图入口。如果应用包含 pages/ 路由体系，需在 app.vue 中显式声明 <NuxtLayout> 与 <NuxtPage />：

   <!-- app.vue -->
   <template>
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>
   </template>

2. 布局组件插槽变更：在 layouts/default.vue 等布局文件中，Nuxt 2 使用的 <nuxt /> 专属标签已被移除，替换为 Vue 3 原生的 <slot /> 插槽标签。
3. 动态路由文件命名法：旧版以下划线开头的动态路由参数（如 pages/_id.vue）在 Nuxt 3 中必须变更为方括号语法：pages/[id].vue。全匹配捕获路由则由 pages/_.vue 变更为 pages/[...slug].vue。
4. 静态资产目录迁移：原有的 static/ 目录统一重命名为 public/，目录下的文件依旧直接映射到站点的根 URL。

步骤三：组件语法与异步数据获取改造

组件编写风格全面拥抱 Vue 3 的 <script setup lang="ts"> 组合式 API。最核心的技术升级在于异步数据获取机制的演进。

在 Nuxt 2 中，页面级组件依赖 asyncData(context) 钩子，组件级依赖 fetch()。在 Nuxt 3 中，这两者被完全废弃，统一由 useAsyncData 和 useFetch 取代，并且可以在页面组件、子组件甚至是自定义 Composable 函数中任意调用。

图 2：Nuxt 2 上下文注入与 Nuxt 3 响应式 Payload 数据流对比

看一个典型的重构示例：

// [旧版] Nuxt 2 Options API (pages/post/_id.vue)
export default {
  async asyncData({ params, $axios, error }) {
    try {
      const post = await $axios.$get(`/api/posts/${params.id}`)
      return { post }
    } catch (e) {
      error({ statusCode: 404, message: '文章未找到' })
    }
  }
}

<!-- [新版] Nuxt 3 组合式 API (pages/post/[id].vue) -->
<script setup lang="ts">
const route = useRoute()
const config = useRuntimeConfig()

// useFetch 会自动为当前请求生成基于 URL 的独立 key，并实现服务端至客户端的 Payload 自动注水
const { data: post, error, pending } = await useFetch(`/api/posts/${route.params.id}`, {
  baseURL: config.public.publicUrl,
  // 当路由动态参数变动时，自动重新触发拉取
  watch: [() => route.params.id]
})

if (error.value) {
  throw createError({ statusCode: 404, statusMessage: '文章未找到', fatal: true })
}
</script>

<template>
  <div v-if="pending">加载中...</div>
  <article v-else-if="post">
    <h1>{{ post.title }}</h1>
    <div>{{ post.content }}</div>
  </article>
</template>

步骤四：状态管理从 Vuex 平滑过渡到 Pinia 与 useState

Nuxt 3 默认不再集成 Vuex。对于状态共享，应根据复杂程度采用不同方案：

• 简单跨组件状态：直接使用 useState()
useState 是 Nuxt 3 专为 SSR 设计的同构响应式状态函数，具有天然的 SSR 友善性与 Payload 序列化能力，可避免跨请求状态污染：

  // composables/useUser.ts
  export const useCurrentUser = () => useState('user-info', () => ({
    id: '',
    name: '游客',
    isLoggedIn: false
  }))

• 复杂业务状态：采用 Pinia
  在 stores/user.ts 中使用 defineStore，搭配 @pinia/nuxt 模块，无需手动注册插件即可在各组件中直接调用：

  // stores/counter.ts
  import { defineStore } from 'pinia'
  
  export const useCounterStore = defineStore('counter', () => {
    const count = ref(0)
    const doubleCount = computed(() => count.value * 2)
    function increment() {
      count.value++
    }
    return { count, doubleCount, increment }
  })

步骤五：服务端 API 路由重构至 Nitro

Nuxt 2 中在 nuxt.config.js 注册的 serverMiddleware 已被彻底废弃，取而代之的是由 Nitro 引擎驱动的 server/ 体系。

所有放置在 server/api/ 目录下的文件会自动映射为 /api/* 的后端接口，且统一使用 defineEventHandler 处理：

// server/api/users/[id].ts
export default defineEventHandler(async (event) => {
  // 提取路由动态参数
  const id = getRouterParam(event, 'id')
  // 提取查询字符串 query 参数
  const query = getQuery(event)

  if (!id) {
    throw createError({ statusCode: 400, statusMessage: '缺少用户 ID' })
  }

  // 处理业务逻辑并直接返回 JS 对象（Nitro 会自动进行 JSON 序列化）
  return {
    id,
    name: `User_${id}`,
    query
  }
})

三、迁移过程中的 6 大高频坑点与排查解决方案

在 Nuxt 2 到 Nuxt 3 的实际迁移过程中，由于执行环境由单纯的 Node 转向跨端同构、构建机制从 Webpack 转为 Vite，开发者通常会遇到一系列阻碍。以下整理了 6 大高频报错与精准解决策略。

图 3：Nuxt 3 迁移期高频报错诊断与修复决策流

坑点 1：服务端渲染报 window is not defined 或 document is not defined

现象表现：在本地 npm run dev 或生产构建打包后打开页面，控制台抛出 ReferenceError: window is not defined 或 document is not defined，导致整个 SSR 渲染崩溃。

原因排查：Nuxt 3 默认在服务端执行组件的 <script setup> 顶层代码。如果引入了 ECharts、Canvas、富文本编辑器或依赖浏览器 DOM 的旧版第三方库，这些库在初始化时尝试访问 window，就会立即报错。

坑点 2：Vue 2 废弃生命周期导致组件挂载与清理失效

现象表现：定时器未清理导致内存泄漏、页面销毁时事件监听没有移除，或报错 TypeError: Cannot read properties of undefined (reading '$router')。

原因排查：Vue 3 废弃了 beforeDestroy 和 destroyed 两个生命周期钩子，分别更名为 onBeforeUnmount 和 onUnmounted。此外，在 <script setup> 中不再存在 this 实例，因此无法再使用 this.$router、this.$route 或 this.$emit。

// 替换为组合式 API 标准钩子
import { onMounted, onBeforeUnmount } from 'vue'

const router = useRouter()
const route = useRoute()
let timer: NodeJS.Timeout | null = null

onMounted(() => {
  timer = setInterval(() => {
    console.log('执行任务', route.path)
  }, 1000)
})

onBeforeUnmount(() => {
  if (timer) clearInterval(timer)
})

坑点 3：CommonJS 模块导入失败（require is not defined）

现象表现：终端或浏览器控制台输出 require is not defined，或者报错 Named export 'xxx' not found in module 'yyy'。

原因排查：Vite 和 Nitro 引擎是纯粹的现代 ESM（ECMAScript Module）架构。旧项目中使用的 const lodash = require('lodash') 语法在浏览器或 ESM 环境下无法执行；同时，部分未经 ESM 封装的老旧 npm 依赖包不能被 Rollup 正确解析。

坑点 4：环境变量与 process.env 访问返回 undefined

现象表现：在组件中使用 process.env.VUE_APP_SECRET 或 process.env.BASE_URL，在本地开发或打包后取出的值全部为 undefined。

原因排查：Nuxt 2 中通过 nuxt.config.js 的 env 配置项把变量在编译时内联到代码中。Nuxt 3 取消了该设计，改用 runtimeConfig 规范，防止前端 bundle 意外泄露服务端核心密钥。

坑点 5：静态资源路径与目录重命名（static/ → public/）

现象表现：图片、字体或 favicon 报 404 找不到文件，或者使用 ~assets 引用资源时构建报错。

原因排查：Nuxt 2 的根目录 static/ 目录在 Nuxt 3 中已规范化更名为 public/。此外，Vite 对于 assets/ 中的资源处理方式与 Webpack 存在差异，不支持动态拼接的隐式 require('~/assets/' + name)。

坑点 6：页面切换时网络请求重复执行或 Payload 水合失配

现象表现：服务端渲染成功输出 HTML，但浏览器加载完成后，网络面板中又立即重发了一次相同的接口请求，并出现控制台警告：[Vue warn]: Hydration completed but contains mismatches。

原因排查：Nuxt 3 的 useAsyncData 依赖于一个唯一的 Key 来把服务端序列化的数据与客户端复用关联。如果使用 useAsyncData 时没有传入固定 Key（或者在客户端手动调用了 $fetch 而非 useFetch），水合阶段客户端无法从 payload.data 中命中缓存，便会降级重新发起网络请求。

// 错误做法：在组件初始化时裸调 $fetch，导致 SSR 与 CSR 各调一次
// const data = await $fetch('/api/profile')

// 正确做法：使用 useFetch 或传入唯一 Cache Key 的 useAsyncData
const route = useRoute()
const { data: profile } = await useAsyncData(
  `user-profile-${route.params.id}`, // 必须保证 SSR 与 CSR 生成完全一致的 key
  () => $fetch(`/api/users/${route.params.id}`)
)

四、迁移完备度核对与生产构建验收

在完成代码与配置的全部重构后，切勿直接发布生产。必须依照以下四个维度的交付基准进行系统性的本地检查与构建验证。

图 4：Nuxt 2 至 Nuxt 3 迁移验收与完备度核对总览

1. 全量类型与语法静态检查

Nuxt 3 深度集成了 TypeScript。在提交构建前，在终端执行以下检查命令，确保项目无遗留类型隐患与废弃语法：

# 生成 Nuxt 类型声明文件并执行严格类型检查
npx nuxi typecheck

若输出中存在有关废弃属性或未定义变量的错误，必须优先清除，避免隐蔽的运行时崩溃。

2. 产物体积分析与依赖打包校验

为确认没有误将大型客户端依赖打入服务端 bundle，可使用 Nuxt 官方分析工具：

# 启动可视化依赖分析
npx nuxi analyze

检查生成的产物报告，重点核对客户端 JS chunk 是否出现意外的旧版库（如重复打包的 moment.js 或 lodash 全量包），确认 UI 组件库均已实现按需分包。

3. 生产构建与跨平台启动验证

Nuxt 3 构建生成的默认产物位于 .output/ 目录下，完全解耦于外层源码与构建工具链。在本地模拟生产启动：

# 执行正式生产环境编译
npx nuxi build

# 使用 Node 直接启动纯粹的生产服务器（无需外层依赖与 devDependencies）
node .output/server/index.mjs

验证应用能够在指定端口（默认 3000）正常启动，检查控制台无 SSR 水合警告，动态路由与静态资源加载均返回 200，即标志着 Nuxt 2 至 Nuxt 3 的完整迁移顺利落地。