Vue3中main.js如何正确配置并挂载Vue Router？

Question

在 Vue 3 中，`main.js` 配置并挂载 Vue Router 时，常见错误是**未正确使用 `createApp()` 创建应用实例，或在 `app.use(router)` 前未调用 `createRouter()` 初始化路由实例**。例如：直接导入 `router` 后未等待其 `createRouter({ ... })` 执行完毕就传入 `app.use()`；或混淆 Vue 2 的 `Vue.use(VueRouter)` 写法；又或在 `app.mount('#app')` 之后才调用 `app.use(router)`，导致路由不生效。此外，若路由配置中 `history: createWebHistory()` 的 base 路径与部署路径不一致（如子目录部署未设 `base: '/my-app/'`），也会引发白屏或 404。还需注意：Vue Router v4 要求 `router` 实例必须在 `createApp(App).use(router)` 中显式安装，且 `setup()` 中不可直接访问 `this.$router`——须通过 `useRouter()` / `useRoute()` 组合式 API 获取。正确顺序应为：导入 → 创建 router → 创建 app → use(router) → mount。

Answer 1

```html

一、基础认知：Vue 3 路由挂载的生命周期契约

在 Vue 3 中，main.js 是应用启动的单点入口，其执行顺序严格遵循“声明式依赖注入”范式。与 Vue 2 的全局插件注册（Vue.use()）不同，Vue 3 的 createApp() 返回一个**可链式配置的应用实例**，所有插件（含 Vue Router）必须在 mount() 前通过 .use() 注入——这是不可协商的时序契约。

二、典型错误图谱与根因归类

错误类型	表现现象	根本原因
Router 实例未就绪即注入	控制台报错 router is not defined 或白屏	异步路由模块（如动态 import）未 await，或 export const router = createRouter(...) 被误写为 export default createRouter(...) 导致解构失败
挂载后才安装插件	路由跳转无响应，<router-view> 不渲染	app.mount('#app') 在 app.use(router) 之后调用，破坏了 Composition API 的响应式上下文初始化时机
base 路径配置失配	子目录部署（如 https://example.com/my-app/）下所有路由 404	createWebHistory() 未传入 base: '/my-app/'，导致 History API 的 URL 解析偏离实际部署路径

三、正确实践：四阶原子化流程

flowchart TD
    A[导入 router 模块] --> B[执行 createRouter 创建实例]
    B --> C[调用 createApp 创建应用实例]
    C --> D[app.use(router) 显式安装]
    D --> E[app.mount('#app') 启动渲染]
    style A fill:#4CAF50,stroke:#388E3C
    style E fill:#2196F3,stroke:#0D47A1

四、代码级验证清单

• ✅ router/index.js 必须导出已初始化的实例：export const router = createRouter({ history: createWebHistory('/my-app/'), routes })
• ✅ main.js 顺序不可颠倒：import { createApp } from 'vue'; import { router } from './router'; const app = createApp(App); app.use(router); app.mount('#app');
• ❌ 禁止：Vue.use(VueRouter)（Vue 2 遗留写法，Vue 3 中 Vue 全局对象已移除）
• ❌ 禁止：app.mount('#app'); app.use(router);（mount 后无法注入响应式能力）

五、高阶陷阱：SSR 与微前端场景下的延伸风险

在 Nuxt 3 或 qiankun 微前端中，若主应用使用 createWebHashHistory() 而子应用强制要求 createWebHistory()，将触发 NavigationDuplicated 异常；此时需统一历史模式，并通过 router.isReady().then(...) 确保路由就绪后再激活子应用。此外，Vite 构建时若 base 配置（vite.config.js）与 createWebHistory(base) 不一致，会导致静态资源 404 连带路由失效——二者必须严格对齐。

六、调试黄金法则：三步定位法

1. 查实例存在性：在 main.js 中 console.log(router)，确认非 undefined 且含 push/replace 方法
2. 验挂载时序：在 app.mount() 前插入 console.log('router installed:', app._context.provides['$router'] !== undefined)
3. 测 base 路径：访问 https://your-domain/base-path/，检查浏览器地址栏是否自动补全 base，且 Network 面板中 index.html 请求路径正确

七、组合式 API 的访问范式迁移

在 setup() 或 script setup 中，this.$router 已被彻底移除。必须显式调用 import { useRouter, useRoute } from 'vue-router'，且 useRouter() 返回的是 reactive router 实例，支持 router.push({ name: 'Home' })，而 useRoute() 提供当前路由的响应式引用——这是 Vue Router v4 对响应式系统深度整合的体现，也是避免 undefined 访问的核心保障。

```