Nuxt 2 迁移到 Nuxt 3 时，服务端渲染配置的核心变化集中在配置文件语法、数据获取方式和 Nitro 引擎替代原有服务器架构。适用场景为已有 Nuxt 2 SSR 项目需要升级，主要风险边界是 Vue 2 组件语法需改写为 Vue 3，部分模块需寻找 Nuxt 3 兼容版本。

命令速用版

迁移时不要直接使用升级命令，建议新建项目后搬运代码：

npx nuxi init my-nuxt-app
cd my-nuxt-app
npm install
npm run dev

如需卸载旧模块并安装 Nuxt 3 兼容版本：

npm uninstall @nuxtjs/color-mode
npm install @nuxtjs/color-mode@latest

为什么会这样

Nuxt 3 的 SSR 配置变化源于架构层面的彻底重构，而非功能迭代。Nuxt 3 不再只是 Vue 的增强插件，而是以 Vue 3 + Vite 为内核重新设计的全栈开发框架。Nitro 引擎替代了原有的服务器架构，带来更小的服务器部署体积和更好的边缘函数支持。配置文件从 nuxt.config.js 改为 nuxt.config.ts，引入 defineNuxtConfig 函数提供完整的 TypeScript 类型支持和配置项验证。

分步处理

第一步：配置文件迁移

Nuxt 2 的直接导出对象方式改为 defineNuxtConfig 函数：

// Nuxt 2 方式
export default {
  // 配置项
}

// Nuxt 3 方式
export default defineNuxtConfig({
  // 配置项
})

检查点：确认 nuxt.config.ts 文件能被 TypeScript 正确识别，配置项有代码提示。

第二步：路由配置调整

路由扩展逻辑从 router.extendRoutes 改为 hooks:'pages:extend'：

// Nuxt 2 方式
export default {
  router: {
    extendRoutes(routes) {
      // 路由扩展逻辑
    }
  }
}

// Nuxt 3 方式
export default defineNuxtConfig({
  hooks: {
    'pages:extend'(routes) {
      // 新的路由扩展逻辑
    }
  }
})

风险边界：routeNameSplitter 配置项不再直接支持，需通过钩子实现相同功能。

第三步：运行时配置迁移

publicRuntimeConfig 和 privateRuntimeConfig 合并为 runtimeConfig：

// Nuxt 3 配置
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // 公开的配置项
    },
    // 私有配置项
  }
})

验证结果：在组件中使用 useRuntimeConfig() 获取配置，确认服务端和客户端都能正确读取。

第四步：数据获取方式改造

asyncData 和 fetch 改为 useAsyncData 和 useFetch：

// Nuxt 2 方式
export default {
  async asyncData({ params, $http }) {
    const post = await $http.$get(`/api/posts/${params.id}`)
    return { post }
  }
}

// Nuxt 3 方式

适用场景：服务端数据预取、SEO 敏感页面、首屏性能优化。

第五步：代理配置调整

@nuxtjs/proxy 改为 nitro.devProxy，仅适用于开发模式：

export default defineNuxtConfig({
  nitro: {
    devProxy: {
      '/api/': {
        target: BASIC_URL,
        changeOrigin: true
      }
    }
  }
})

风险边界：build 后没有代理，生产环境需单独配置。

第六步：布局系统更新

布局使用方式改为 definePageMeta：

检查点：确认 layouts 目录下的布局文件能被正确引用。

怎么验证是否生效

查看服务端渲染输出：启动开发服务器后，查看页面源代码是否包含完整的 HTML 内容而非空骨架。检查 SEO 元信息：使用浏览器开发者工具查看 head 标签是否正确注入。测试数据预取逻辑：禁用 JavaScript 后刷新页面，确认基础内容仍可访问。查看 Nitro 输出：生产构建后检查.output 目录是否生成，确认服务器代码已正确打包。

常见坑

模块系统不再区分 buildModules 和 modules，所有模块都在 modules 数组中声明。本地模块引用需明确指定入口文件路径，如'~/modules/my-module/index'而非'~/modules/my-module'。head 配置需放到 app:{head:{}} 中，旧写法会失效。Vuex 建议迁移到 Pinia，如继续使用 Vuex 需升级到 Vuex 4 并配置 InjectionKey。Volar 插件需禁用 Vetur，否则 Vue 3 语法提示会失效。devProxy 仅适用于开发模式，生产环境需单独配置反向代理。

常见问题

Nuxt 2 项目能直接升级吗

不建议直接升级，官方推荐新建 Nuxt 3 项目后搬运代码。Nuxt 2 和 Nuxt 3 基本是重写，配置结构和 API 都有结构性变化，原地升级容易遗漏配置项。

SSR 性能有提升吗

公开资料中没有看到可靠的量化数据。Nuxt 3 基于 Nitro 引擎和 Vite 构建工具，官方宣称开发服务器启动时间有显著缩短，但具体数值因项目规模而异。

TypeScript 需要额外配置吗

Nuxt 3 原生支持 TypeScript，不需要额外配置。使用 nuxt.config.ts 代替 nuxt.config.js 即可获得完整的类型支持和代码提示。

旧模块还能用吗

部分模块需要寻找 Nuxt 3 兼容版本。如 Color Mode 模块需安装@nuxtjs/color-mode@latest，一些 Nuxt 2 专用模块可能不再维护，需寻找替代方案。

参考来源

• 知乎 - 01.Nuxt3 简介和开发环境搭建
• Nuxt 3 配置迁移指南：从 Nuxt 2 到 Nuxt 3 的平滑过渡
• 博客园 - nuxt2 升级 nuxt3 - 庞永胜
• CSDN 博客 - 从 Vue 2 迁移到 Nuxt 3，我用 create-nuxt-app 踩了这些坑
• CSDN 博客 - Nuxt.js 3 服务端渲染 (SSR) 入门：构建更好的 SEO 与首屏体验
• 从 Nuxt 2 迁移到 Nuxt 3:Color Mode 模块适配指南
• CSDN 博客 - nuxt2 项目迁移 nuxt3_nuxt 支持 vue2 还是 vue3
• Nuxt 3 组件选项迁移指南：从 Nuxt 2 到 Nuxt 3 的升级路径
• Nuxt3 试水 (三) 之 nuxt2 升级到 nuxt3
• Nuxt3 ,Vue3 的混合渲染框架