Vue 3 + Vue Router 路由迁移到 Nuxt4 完整指南

在 Vue 3 项目中，如果你使用了手写 Vue Router，迁移到 Nuxt4 时，需要注意 Nuxt4 的文件系统路由和布局机制。本文整理了完整的迁移方法，并提供了示例代码。

1. Nuxt4 的路由机制

• 文件系统路由：Nuxt4 自动根据 pages/ 目录生成路由，不需要手写 createRouter。
• 布局机制：在 layouts/ 目录定义布局，然后在页面里指定 definePageMeta({ layout: 'admin' })。
• 404 页面：可以用 [...all].vue 捕获所有未匹配路由，或者在 app/router.options.js 手写自定义路由。

2. 原来的 Vue Router 配置示例

import { createRouter, createWebHistory } from 'vue-router';
import AdminIndex from '@/pages/admin/index.vue';
import About from '@/pages/about.vue';
import NotFound from '@/pages/404.vue';
import AdminLogin from '@/pages/admin/login.vue';
// ...其他组件

const routes = [
  { path: '/admin', component: Admin, children: [
      { path: '/admin', component: AdminIndex, meta: { title: '仪表盘' } },
      // ...其他后台子路由
    ]
  },
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFound },
  { path: '/login', component: AdminLogin, meta: { title: '登录页' } },
  { path: '/', component: Index, meta: { title: '首页' } },
  // ...前端其他页面
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});

export default router;

3. Nuxt4 文件路由改造

3.1 调整 pages/ 目录结构

pages/
│── index.vue                # 首页 (/)
│── about.vue                # 关于页 (/about)
│── login.vue                # 登录页 (/login)
│── article/
│     └── detail.vue         # (/article/detail)
│── category/
│     ├── index.vue          # (/category)
│     └── list.vue           # (/category/list)
│── tag/
│     ├── index.vue          # (/tag)
│     └── list.vue           # (/tag/list)
│── archive.vue              # (/archive)
│── domain.vue               # (/domain)
│── admin/
│     ├── index.vue          # (/admin)
│     ├── login.vue          # (/admin/login)
│     ├── article-list.vue   # (/admin/article/list)
│     ├── category-list.vue  # (/admin/category/list)
│     ├── tag-list.vue       # (/admin/tag/list)
│     ├── blog-setting.vue   # (/admin/blog/setting)
│── [...all].vue             # 404 页面

3.2 404 页面

pages/[...all].vue：

<template>
  <div class="flex flex-col items-center justify-center h-screen text-center">
    <h1 class="text-5xl font-bold text-red-500">404</h1>
    <p class="mt-4 text-lg">页面不存在</p>
    <NuxtLink to="/" class="mt-6 text-blue-500 hover:underline">返回首页</NuxtLink>
  </div>
</template>

3.3 Admin 布局

layouts/admin.vue：

<template>
  <div>
    <header>后台管理头部</header>
    <main>
      <slot />
    </main>
  </div>
</template>

在后台页面中指定布局：

<script setup>
definePageMeta({
  layout: 'admin'
})
</script>

4. 可选：自定义 router（方法三）

如果你想手写一些特殊路由（比如 404），可以在项目根目录下新建：

app/router.options.js：

export default {
  routes: (_routes) => [
    ..._routes, // 保留 Nuxt 自动生成的路由

    {
      name: 'NotFound',
      path: '/:pathMatch(.*)*',
      component: () => import('~/pages/404.vue')
    }
  ]
}

✅ 这样 Nuxt4 会同时保留自动生成的路由，并使用你手写的 404。

5. 总结迁移原则

1. 页面路由 → 尽量用 Nuxt4 文件路由，减少手写。
2. 布局 → 用 layouts/ + definePageMeta 代替 Vue Router children。
3. 404 或特殊路由 → 可用 [...all].vue 或 router.options.js 自定义。
4. Meta 信息 → 在页面里用 definePageMeta({ title: '页面标题' })。

这样，你原来 Vue Router 的整个配置就可以干净迁移到 Nuxt4，同时保留 404、后台布局、前端页面 等功能。