vue3+vite+ts 路由配置及问题总结

于 2025-05-07 17:00:22 发布
阅读量805 收藏 22
点赞数 26
分类专栏： vue 文章标签： vue.js javascript 前端
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/shilh0107/article/details/147769944
版权

在Vite + Vue3 + TypeScript项目中集成Vue Router

一、安装Vue Router
安装适用于Vue3的Vue Router v4：

npm install vue-router@4
# 或
yarn add vue-router@4

二、配置路由文件

  1. 创建路由配置
    在src/router/index.ts中定义路由规则：

    import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'
import Home from '@/views/Home.vue'  // 使用@别名简化路径

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'Home',
    component: Home
  },
  {
    path: '/about',
    name: 'About',
    component: () => import('@/views/About.vue') // 动态导入组件
  }
]

const router = createRouter({
  history: createWebHistory(), // 或createWebHashHistory()
  routes
})

export default router

  2. 路径别名配置（可选）
    在vite.config.ts中设置@指向src目录：

    import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
})

    并在tsconfig.json中添加：

    {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

三、挂载到Vue应用
在main.ts中引入路由：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#app')

四、使用路由组件

  1. 基本导航
    在模板中使用<router-link>和<router-view>：

    <!-- App.vue -->
<template>
  <nav>
    <router-link to="/">Home</router-link>
    <router-link to="/about">About</router-link>
  </nav>
  <router-view />
</template>

  2. 编程式导航
    在组合式API中使用useRouter：

    import { useRouter } from 'vue-router'

const router = useRouter()
const goToAbout = () => {
  router.push('/about')
}

五、进阶配置

  1. 动态路由参数
    定义带参数的路由：

    {
  path: '/user/:id',
  component: () => import('@/views/User.vue'),
  props: true // 通过props接收参数
}

    在组件中接收：

    defineProps<{ id: string }>()

  2. 路由守卫
    全局前置守卫示例：

    router.beforeEach((to, from, next) => {
  if (to.meta.requiresAuth && !isLoggedIn()) {
    next('/login')
  } else {
    next()
  }
})

常见问题解决
• 组件未找到错误：检查vite.config.ts和tsconfig.json的路径别名配置

• 页面不跳转：确保<router-view>已添加到父组件中

• TS类型报错：使用RouteRecordRaw类型定义路由数组

完整示例可参考Vite官方文档及Vue Router 4文档。

常见问题

Cannot find module ‘path’ or its corresponding type declarations

一、问题原因
该错误表示 TypeScript 无法识别 Node.js 内置模块 path 的类型声明，常见于以下场景：

  1. 在 vite.config.ts 中使用 path.resolve() 配置路径别名
  2. 在 TypeScript 文件中引用了 Node.js 原生模块
  3. 未正确配置 TypeScript 类型声明

二、解决方案步骤

  1. 安装 Node.js 类型声明包
npm install -D @types/node

这是最关键的步骤，该包提供了 Node.js 模块的 TypeScript 类型定义。

  1. 配置 tsconfig.json
{
  "compilerOptions": {
    "types": ["node"],        // 声明 Node.js 类型
    "baseUrl": ".",           // 路径别名的必要配置
    "paths": {
      "@/*": ["src/*"]        // 路径别名映射
    }
  }
}
  1. 调整模块导入方式
    在 vite.config.ts 中使用以下两种写法之一：
// 方式一：使用命名空间导入（推荐）
import * as path from 'path'

// 方式二：启用 allowSyntheticDefaultImports
// 在 tsconfig.node.json 中添加：
{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true
  }
}

这是为了避免 "模块 'path' 只能在使用 'allowSyntheticDefaultImports' 标志时进行默认导入 的错误。

  1. 验证 Vite 配置
    确保 vite.config.ts 的路径别名配置正确：
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import * as path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src') // 使用 path 模块
    }
  }
})
  1. IDE 缓存清理
    执行以下操作确保类型声明生效：
  2. 关闭 VS Code
  3. 删除 node_modules 和 package-lock.json
  4. 重新运行 npm install
  5. 重启 IDE

三、附加说明

  1. 项目结构要求：@/ 路径别名需对应 src/ 目录的实际位置
  2. 版本兼容性：需确保 @types/node 版本与 Node.js 运行环境版本匹配
  3. 生产环境处理：该错误仅影响开发时类型检查，不会影响构建后的代码运行

通过上述步骤，可解决 常见的 path 模块类型声明问题。如果问题依旧存在，建议检查项目是否同时存在多个冲突的 tsconfig.json 文件，或尝试升级 TypeScript 到最新版本。

‘RouteRecordRaw’ is a type and must be imported using a type-only import when ‘verbatimModuleSyntax’ is enabled

一、错误原因
此错误发生在以下场景中：

  1. 项目中启用了 verbatimModuleSyntax（TS 5.0+ 的特性）
  2. 使用常规 import 语法导入了纯类型 RouteRecordRaw
  3. Vue Router 4.x 的类型声明设计需要显式区分类型和运行时模块

二、解决方案

  1. 使用类型专用导入语法（推荐）
    修改路由配置文件的导入方式：
// 正确写法
import { createRouter, createWebHistory } from 'vue-router'
import type { RouteRecordRaw } from 'vue-router' // 添加 type 修饰符

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    component: () => import('@/views/Home.vue')
  }
]
  1. 配置 TypeScript
    在 tsconfig.json 中调整编译选项：
{
  "compilerOptions": {
    "verbatimModuleSyntax": false, // 关闭严格模式（不推荐长期方案）
    "types": ["node", "vue-router"] // 确保类型声明加载
  }
}
  1. 进阶场景处理
    当扩展路由类型时：
// 自定义类型需要继承时
import type { RouteRecordRaw } from 'vue-router'

type CustomRoute = RouteRecordRaw & {
  hidden?: boolean // 扩展属性
}

const routes: CustomRoute[] = [...] //

三、最佳实践

  1. 类型与实现分离
    始终使用 import type 导入纯类型声明，常规 import 仅用于运行时模块

  2. 工具链优化
    使用自动化修复工具：

    npx fix-verbatim-module-syntax ./tsconfig.json #

  3. 配置规范
    保持 verbatimModuleSyntax: true 并配合 ESLint 规则：

    // .eslintrc
{
  "rules": {
    "@typescript-eslint/consistent-type-imports": "error"
  }
}

四、常见误区

错误做法正确做法原理说明
import { RouteRecordRaw }import type { RouteRecordRaw }避免类型声明被编译到 JS 运行时
关闭所有类型检查使用 verbatimModuleSyntax保持类型安全与编译准确性
混合导入方式分离类型与实现符合 TS 5.0+ 模块规范

五、关联问题排查

  1. 如果出现 Cannot find module 'vue-router'，请检查 @types/node 安装
  2. 动态路由配置需确保组件路径正确
  3. 编程式导航参数传递应使用 query 或 state

通过以上方案，可有效解决 Vue3 + TypeScript 项目中与路由类型相关的编译错误。建议长期保持 verbatimModuleSyntax 启用状态以提升代码质量。

Cannot find module ‘@/router/index’ or its corresponding type declarations

以下是解决 Cannot find module '@/router/index' or its corresponding type declarations 错误的完整方案，结合了多个文档的最佳实践：

一、核心原因分析
此错误通常由以下原因导致：

  1. 路径别名未正确配置：@/ 未映射到 src/ 目录
  2. TypeScript 类型声明缺失：未声明 .ts 模块或路径别名类型
  3. IDE 缓存或配置问题：旧配置未及时更新

二、分步解决方案

  1. 配置路径别名
    步骤一：修改 vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path' // 确保已安装 @types/node

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'), // 映射 src 目录
      '@router': path.resolve(__dirname, 'src/router') // 扩展路由别名
    }
  }
})

步骤二：更新 tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@router/*": ["src/router/*"] // 同步别名配置
    },
    "types": ["node"] // 启用 Node.js 类型声明
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"] // 包含路由文件
}
  1. 声明模块类型
    在 src/vite-env.d.ts 中添加：
declare module '@/router/index' {
  import { Router } from 'vue-router'
  const router: Router
  export default router
}
// 或使用通配符声明
declare module '@router/*' {
  const value: any
  export default value
}
  1. 验证关键依赖
# 安装必要依赖
npm install -D @types/node vue-router@4

三、进阶排查指南

现象解决方案关联文档
IDE 仍报错1. 删除 node_modules/.vite 目录
2. 重启 VS Code 并执行 Developer: Reload Window
生产构建失败在 package.json 中添加类型检查命令：
"build": "vue-tsc && vite build"
动态导入报错使用显式路径：import router from '@/router/index' 代替 @/router
嵌套路径问题在 tsconfig.json 中增加：
"moduleResolution": "node"

四、配置验证示例

  1. 文件结构验证

    src/
└─ router/
   └─ index.ts  # 确保文件名和路径完全匹配

  2. 代码导入测试

    // 正确写法（大小写敏感）
import router from '@/router/index' 

// 错误示例（路径不完整）
// import router from '@/router'

五、最佳实践建议

  1. 统一别名规范：建议使用 @/ 作为主别名，避免多级别名导致混乱
  2. 类型声明集中管理：在 types/ 目录下创建 global.d.ts 统一管理自定义类型
  3. 启用 Volar 插件：禁用 Vetur 并安装 Volar 以获得更好的 Vue3 支持

若问题仍未解决，建议对比 [Webpage 8] 的配置流程图进行逐项检查。

Module ‘“./router/index”’ has no exported member ‘router’. Did you mean to use ‘import router from “./router/index”’ instead?ts(2614)

一、核心原因分析

  1. 导出方式错误：路由实例未正确使用 export default 导出（常见于 Vue Router 4.x 配置）
  2. 导入语法错误：尝试用命名导入（import router ）代替默认导入（import {router}）
  3. 模块声明缺失：TypeScript 无法识别 .ts 模块的默认导出类型

二、分步解决方案

  1. 修正路由导出方式
    在 src/router/index.ts 中确保使用 默认导出：
// ✔️ 正确写法
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [...] 
})

export default router // 必须使用 default 导出
  1. 修正模块导入语法
    在组件或 main.ts 中使用 默认导入：
// ✔️ 正确写法（无花括号）
import router from '@/router/index' // 或简写为 '@/router'

// ✖️ 错误写法（使用了命名导入）
import { router } from '@/router' // 触发 TS2614 错误
  1. 增强类型声明（可选）
    在 src/env.d.ts 中添加模块类型声明：
declare module '@/router' {
  import type { Router } from 'vue-router'
  const router: Router
  export default router // 声明默认导出类型
}

三、进阶验证步骤

验证点正确示例错误示例
导出语句export default routerexport { router }
导入路径@/router（自动识别 index.ts）@/router/index.ts（冗余后缀）
路由实例createRouter() + WebHistorynew VueRouter()（Vue2 语法）

四、关联配置检查

  1. Vite 路径别名（vite.config.ts）：
    resolve: {
  alias: {
    '@': path.resolve(__dirname, 'src') // 确保路径映射
  }
}
  2. TypeScript 配置（tsconfig.json）：
    {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"] // 同步别名配置
    }
  }
}

五、常见误区修正

// ✖️ Vue2 风格的导出（适用于 vue-router@3）
import VueRouter from 'vue-router'
export default new VueRouter({...}) 

// ✔️ Vue3 风格的导出（适用于 vue-router@4）
import { createRouter } from 'vue-router'
export default createRouter({...})

若问题依旧存在，建议检查 node_modules/vue-router/package.json 确认安装版本是否为 4.x 系列。

vue3-vite-ts-Vant：vue3 + vite + ts + Vant + vuex +路由器
03-04
vue3-vite-ts-Vant vue3 + vite + ts + Vant + vuex +路由器 项目详细介绍 项目预览
Vue3+Vite4+TS 后台模板
06-08
Vue3+Vite4+TS 后台模板是一款基于最新技术栈构建的高效、现代化的前端开发框架，专为后台管理界面设计。该模板利用了Vue.js的最新版本Vue3，搭配快速构建工具Vite4，以及TypeScript的静态类型检查，提供了强大的...
“ComponentInternalInstance”是一种类型，必须在启用 “verbatimModuleSyntax“ 时使用仅类型导入进行导入。ts(1484)
xiaoxiaoqiliuhai的博客
02-21 983
解决办法2: 不想加type的话， 将根目录下的ts配置文件tsconfig.app.json 中的。解决办法1（推荐）: 加type 说明导入的是type类型。新建vue3项目，把之前的公共文件拿来服用就出现了这个错误。选项中添加代码， 错误提示就消失。
创建vue3 + vite + ts 项目
最新发布
jialong_web的博客
03-18 485
vue3 + vite + ts 项目简单搭建
vite构建vue3+Ts项目 并配置路由router
ZHENGCHUNJUN的博客
02-27 5386
找不到模块“@/views/About.vue”或其相应的类型声明，这个警告说明 Vue Router 没有找到与路径 "/src/views/About" 匹配的路由。Vue Router 的路径匹配是基于配置的路由路径而不是实际文件路径。对于 Vue 3，Vue Router 是一个单独的库，因此你需要安装它作为项目的依赖。的文件夹，然后在该文件夹中创建一个名为。能够正确地映射到对应的组件，确保路由的。中确保路由的配置是正确的，，用于显示当前路由对应的组件。
vite vue3 ts vue-router vue-store 创建项目
qq_1126043450的博客
12-01 883
vite vue3 ts vue-router vue-store 创建项目
vite+vue3+ts路由vue-router的使用，以及参数传递
热门推荐
jason_renyu的博客
03-03 1万+
前边我们分别介绍了pinia以及vite+vue3+ts这套组合的组件传参方式，以及简单todolist的demo，这些基本上都够一个项目的开发了，这时候是不是觉得还缺点什么？那就是路由vue-router，以及数据请求axios了。 axios的用法与vue2的差别不大，就是一些ts的语法问题，所以也就不对axios的用法做介绍了，本篇来介绍下vue-router路由的使用。 本篇也不从创建项目开始了，对vite+vue3这套项目不了解的可以看下《vite+vue3+ts简单例子todolist》,本篇
Vue3+Vite+Ts配置路由、Pinia 配置和简单介绍、配置 SCSS
irisMoon06的博客
12-19 612
Vue3+Vite+Ts配置路由、Pinia 配置和简单介绍、配置 SCSS
vue3+ts+vite+router+vuex+api请求封装
12-29
Vue3+TS+Vite+Router+Vuex+API请求封装是现代前端开发中的一个典型组合，用于构建高效、可维护的后台管理系统。这个脚手架提供了完整的开发环境配置和基础架构，使得开发者能够快速搭建后台应用。下面将详细介绍这个...
Vue3+Vite+TypeScript+Ant Design Vue+Pinia等主流技术的后台管理系统项目.zip
01-03
Vue3+Vite+TypeScript+Ant Design Vue+Pinia是一个现代前端开发的组合，用于构建高效、可维护的后台管理系统。这个项目充分利用了这些技术的优势，提供了丰富的功能和优化的开发体验。以下是对这些技术及其在后台...
基于Vite+Vue3+TS+Nuxt3的仿爱彼迎网站源码.zip
06-21
《构建基于Vite+Vue3+TS+Nuxt3的仿爱彼迎(Airbnb)网站源码解析》 在现代Web开发中，快速迭代和高效构建成为开发者关注的重点。本项目"基于Vite+Vue3+TS+Nuxt3的仿爱彼迎网站源码"正是这样一个实践案例，它巧妙地...
Vite+vue3+ts如何使用router
weixin_48288941的博客
08-17 311
路径（参考大部分人都是这么创建的）：src/router/index.ts。对应的component要根据自己的路径创建好。ts内容根据自己项目自定义，我自己的是这么写的。2、创建router对应的ts文件。1、安装router。3、使用router。
vue3+vite+ts如何使用路由
weixin_44594219的博客
09-02 633
在vue3+vite+ts项目中如何使用路由
vue3+ts+vite自适应项目——路由、layout布局
DW14687的博客
05-01 3568
以上就是今天得内容，路由配置，下一章准备将请求~
vite搭建vue3+ts项目（包含sass，vue-router）
luffy的博客
10-19 1055
相关资料网址 vue3.0官网：https://cn.vuejs.org/ vite官网： https://vitejs.cn/ 通过vite进行创建的步骤 npm i vite -g vite -v //根据是否返回版本号判断是否下载成功 npm init vite-app 项目名 创建项目 cd 文件夹名 npm i npm run dev //看到网址打开 前五步为vite的使用搭建 npm i -S typescript vue-router@next //安装ts和router 配置
Vue3 + vite + Ts + Router 路由注册、使用方法
qq_33365152的博客
08-20 469
Vue3 + vite + Ts + Router 路由注册、使用方法
使用Vite创建Vue3项目 配置路由+路径（包教包会）
比鲁斯大人的博客
11-08 1399
【代码】使用Vite创建Vue3项目 配置路由+路径（包教包会）
Vue3 + Vite + Ts + Router搭建项目
新人一枚，互相学习哦！
11-07 784
基于vite+ts+vue3搭建项目
Vue3 + Vite + Ts:路由 vue-router 的基本使用
A88552211的博客
07-12 1599
Vue3以后写的路由
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值