或 yarn add vue-router@4

不少做Vue开发的朋友最近会问：“Vue Router ESM 是什么，该怎么用？” 其实这和现代前端的模块化趋势、性能优化需求密切相关，今天咱们就从概念、特性、用法到避坑，把Vue Router ESM 聊透，帮你在项目里用得顺手～

Vue Router ESM 到底是什么？

先理解ESM（ECMAScript Module）：它是浏览器和现代构建工具（像Vite、Webpack 5+）支持的模块化标准，用import/export语法，能让代码按需加载、实现Tree Shaking（摇树优化，剔除未使用代码）。

而Vue Router ESM，是Vue Router 针对ESM 规范做的模块化分发形式，和传统CommonJS（用require）的用法有本质区别。

举个实际场景对比：

• 传统CommonJS 写法：引入Vue Router 时，会把整个库全量打包（哪怕只用到路由跳转功能），冗余代码多。
• ESM 写法：构建工具能精准“挑出”你用到的createRouter createWebHistory 等功能，没用到的代码直接过滤，打包后体积更小。

再看版本适配：Vue Router 4+ 对ESM 的支持是“原生级”的——package.json 里的module 字段已经指向ESM 入口，所以只要用现代构建工具（比如Vite 初始化的Vue 3 项目），导入vue-router 时默认就走ESM 模式，不用额外配置～

Vue Router ESM 核心特性有哪些？

把每个特性掰开揉碎讲,结合例子更易懂：

Tree Shaking 自由：包体积“瘦”下来

Tree Shaking 是ESM 最核心的优势之一，比如你只需要创建路由实例、用哈希模式，Vue Router 里没用到的代码（比如其他历史模式实现、旧版兼容逻辑）就会被打包工具过滤。

看代码对比：

// 传统CommonJS 写法（全量引入，冗余代码多）
const VueRouter = require('vue-router')
const router = new VueRouter({ ... })
// ESM 写法（只拿需要的，多余代码被摇掉）
import { createRouter, createWebHashHistory } from 'vue-router'
const router = createRouter({ 
  history: createWebHashHistory(),
  routes: [...]
})

实际项目中,这种写法能让路由部分包体积减少30%+（具体看功能使用量），对移动端H5、小程序这类“体积敏感型”场景特别友好。

按需加载+代码拆分：页面加载更快

Vue Router ESM 天然支持动态导入组件，配合构建工具实现“路由级代码拆分”，比如用户访问首页时，只加载首页组件；访问个人中心时，再加载对应组件，不用一次性打包所有页面。

代码示例：

const User = () => import('./views/User.vue') // 动态导入，构建工具拆分出单独chunk
const routes = [
  { path: '/user', component: User }
]

这样首屏加载的JS 体积大幅减少，用户打开页面更快，尤其适合页面多、组件复杂的中大型项目。

和现代构建工具“无缝贴贴”

不管是Vite（天生基于ESM，开发时秒级热更新），还是Webpack 5+（对ESM 支持更完善），Vue Router ESM 都能完美适配：

• Vite 开发时，修改路由配置或组件，浏览器立即更新，不用重启项目；
• Webpack 5 里，通过optimization 配置能让Tree Shaking 更彻底。

对Composition API 更友好

Vue 3 主推Composition API（组合式API），Vue Router ESM 里的useRouter useRoute 等工具函数，就是为组合式API 设计的。

比如在setup 中获取路由参数：

import { useRoute } from 'vue-router'
const MyComponent = {
  setup() {
    const route = useRoute()
    console.log(route.params.id) // 直接拿路由参数，不用this.$route
  }
}

这种写法更贴合Vue 3 响应式逻辑，代码简洁，和React Hook 思路类似，新手好理解、老手写着爽～

哪些场景适合用 Vue Router ESM？

不是所有项目都得用ESM,得看场景匹配度：

新建现代前端项目（尤其是Vite 初始化的）

用Vite 创建Vue 3 项目时，默认就是ESM 生态：package.json 依赖是最新版，构建工具天然支持import/export，这种情况下用Vue Router ESM 是“顺势而为”，开发体验拉满，打包体积也能优化到位。

组件库/工具库开发

如果做Vue 生态的组件库（比如封装UI 组件+路由逻辑），用ESM 模式导出代码，能让使用者也享受Tree Shaking 福利，比如组件库的路由工具函数，用户只导入需要的部分，不会拖大项目体积。

性能敏感型应用（比如移动端、低配置设备）

像电商APP 的H5 页面、IoT 设备的Web 控制端，对加载速度和内存占用要求高，Vue Router ESM 的Tree Shaking 和动态导入，能把首屏JS 体积压到最小，让页面在弱网、低配设备上快速打开。

渐进式迁移旧项目

如果项目还在用Vue 2 + Vue Router 3（CommonJS 模式），想逐步升级到Vue 3 + Vue Router 4，ESM 模式可作为“中间态”：先把路由部分改成ESM 写法，再慢慢迁移其他模块，降低重构风险。

Vue Router ESM 具体怎么用？（附实操步骤）

光说不练假把式,这部分给清晰步骤+代码示例：

步骤1：安装依赖（确保版本匹配）

Vue Router 4+ 才对ESM 有完善支持，且必须和Vue 3 配套，用npm/yarn 安装：

npm install vue-router@4  # Vue 3 需搭配vue-router 4+```  
安装后，`package.json` 里能看到`vue-router` 版本≥4，接下来配置路由。  
### 步骤2：基础路由配置（ESM 风格）  
新建`src/router/index.js`（或ts），用ESM 语法写：  
```js
// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'
import About from '../views/About.vue'
const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About }
]
const router = createRouter({
  history: createWebHistory(), // HTML5 历史模式（URL 美观，需后端配合）
  // 若用哈希模式，替换为 createWebHashHistory()
  routes
})
export default router

然后在src/main.js 里挂载路由：

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router' // 导入路由配置
const app = createApp(App)
app.use(router) // 注入路由
app.mount('#app')

这样基础路由就跑通了,访问 跳Home，/about 跳About～

步骤3：动态导入组件（路由级代码拆分）

如果页面多,想优化首屏加载，把组件改成动态导入：

// src/router/index.js
// 静态导入 → 动态导入
const Home = () => import('../views/Home.vue')
const About = () => import('../views/About.vue')
const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About }
]
// ... 其他配置和之前一致

构建工具（Vite/Webpack）会把Home、About 拆成单独JS 文件，用户访问对应路由时才加载，首屏体积瞬间减小～

步骤4：用Composition API 操作路由

在组件里用useRouter useRoute 实现跳转、拿参数：

<template>
  <button @click="goAbout">去关于页</button>
  <p>当前ID：{{ route.params.id }}</p>
</template>
<script setup>
import { useRouter, useRoute } from 'vue-router'
const router = useRouter()
const route = useRoute()
const goAbout = () => {
  router.push('/about') // 编程式导航
}
</script>

这种写法比Vue 2 的this.$router 更灵活，也更贴合组合式API 逻辑～

步骤5：和Vite 深度配合（开发体验拉满）

Vite 对ESM 支持是“原生级”的，用Vue Router ESM 时，开发阶段热更新（HMR）特别快：

• 修改路由配置里的path，保存后浏览器立即更新，不用重启项目；
• 修改组件里的路由逻辑,也能精准热更，不用刷新整个页面。

如果是Webpack 项目，确保版本≥5，且在webpack.config.js 里开启optimization.splitChunks，让代码拆分更智能～

使用 Vue Router ESM 容易踩哪些坑？怎么避？

新人用ESM 常掉坑，提前避坑能少熬夜：

坑1：导入路径错误，导致打包体积没优化

现象：明明用了ESM，打包后体积还是很大，Tree Shaking 没生效。
原因：导入方式不对，比如用默认导出+全量引入：

// 错误示范：全量引入，Tree Shaking 失效
import VueRouter from 'vue-router' 
const router = VueRouter.createRouter(...)

解决：严格用命名导出（{ createRouter, ... }），别用默认导出+链式调用，让构建工具识别未使用代码。

坑2：构建工具不兼容（比如Webpack 4）

现象：项目用Webpack 4，导入ESM 语法时报错，或打包后代码运行异常。
原因：Webpack 4 对ESM 支持不完善，默认把ESM 当CommonJS 处理，导致Tree Shaking 失效、动态导入出错。
解决：

• 优先升级Webpack 到5+；
• 若暂时不能升级,在webpack.config.js 里配置：

  module.exports = {
    module: {
      rules: [
        {
          test: /\.m?js$/,
          resolve: {
            fullySpecified: false // 兼容ESM 导入
          }
        }
      ]
    }
  }

坑3：动态导入组件时，缓存导致更新不及时

现象：修改了动态导入的组件（比如Home.vue），开发时热更新没生效，必须手动刷新页面。
原因：浏览器对动态导入的JS 文件做了缓存，构建工具的HMR 没穿透到动态导入的chunk。
解决：

• Vite 里不用额外配置（Vite 自带HMR 处理动态导入）；
• Webpack 5+ 可开启output.hashFunction: 'xxhash64' 或用react-refresh 类插件优化HMR。

坑4：历史模式下，部署到子路径404

现象：用createWebHistory() 模式，本地开发正常，部署到服务器子路径（比如https://xxx.com/my-app/）后，刷新页面报404。
原因：HTML5 历史模式需要服务器配置“前端路由 fallback”，且createWebHistory 的base 参数没设置。
解决：

1. 服务器配置：所有请求 fallback 到index.html（nginx、Apache 都有对应配置方法）；
2. 路由里设置base：

   const router = createRouter({
     history: createWebHistory('/my-app/'), // base 设为子路径
     routes: [...]
   })

Vue Router ESM 会怎么发展？

Vue 生态一直在进化，Vue Router ESM 也会跟着场景迭代：

更深度整合Vue 的响应式能力

Vue 3 的响应式基于Proxy，未来Vue Router 可能在路由变化监听、参数响应式上做更细优化，让useRoute 的参数变化更及时触发组件更新，减少手动watch 的需求。

适配更多元的路由场景

比如微前端（Micro Frontends）场景下，Vue Router ESM 可能支持更灵活的路由隔离、跨应用路由跳转；或与Web Components 结合，让路由逻辑在复杂组件化架构里更易用。

性能优化持续加码

包体积会继续“瘦身”——比如把边缘功能做成可选插件（像路由守卫高级功能），让基础包更小；动态导入的加载策略也会更智能（比如预加载用户可能访问的下一个页面），提升交互流畅度。

与SSR/SSG 更紧密配合

Nuxt 3 这类框架已深度整合Vue Router ESM，未来Vue Router 可能在服务端渲染（SSR）、静态站点生成（SSG）上提供更简洁API，让SEO 友好型项目的路由配置更丝滑。

看完这些,你应该对Vue Router ESM 从“是什么”到“怎么用”，再到“未来趋势”有了清晰认知～ 实际项目里，建议从新建Vite 项目开始练手，把动态导入、Composition API 这些特性用起来，感受体积优化和开发体验的提升，如果是旧项目迁移，不妨先从路由模块下手，逐步过渡到ESM 模式，踩坑时对照上面的避坑指南，基本能解决90% 的问题～ 要是你在实践中遇到新问题，随时留言讨论，咱们一起折腾前端技术～