vue router 报 history.createHref is not a function 是怎么回事？该怎么解决？

terry 3小时前阅读数 6 #Vue

文章标签 createHref

在Vue项目里写路由的时候，突然遇到控制台报错“history.createHref is not a function”，是不是瞬间脑袋嗡一下？别慌，这个问题大概率是路由配置、版本或者自定义逻辑哪里“没对上号”导致的，接下来咱们一步步拆解原因，再对应找解决办法,把这个报错彻底解决掉～

Vue Router版本“代际差异”搞出来的乌龙

先说说Vue Router的版本问题，Vue Router 3.x和4.x在用法上有本质区别，很多同学升级项目时没注意细节，就容易触发这个报错。

举个例子，Vue Router 3.x（对应Vue 2）是这么玩的：

import Vue from 'vue'
import VueRouter from 'vue-router'
Vue.use(VueRouter) // 先注册插件
const router = new VueRouter({
  mode: 'history', // 指定history模式
  routes: [...]
})
export default router

但到了Vue Router 4.x（对应Vue 3），玩法完全变了——要用createRouter + createWebHistory这套新API：

import { createRouter, createWebHistory } from 'vue-router'
const router = createRouter({
  history: createWebHistory(), // 这里传入history实例
  routes: [...]
})
export default router

要是你在Vue 3项目里，还照着3.x的写法用new VueRouter + mode: 'history'，或者在Vue 2项目里错误引入4.x的包，就会让路由内部的history对象“缺斤少两”，因为4.x里已经没有mode这个配置项了，改用createWebHistory等方法生成history实例；而3.x的history对象结构和4.x也不一样，自然就找不到createHref方法。

所以第一步要做的是：打开package.json，检查Vue和Vue Router的版本是否匹配（Vue 2配3.x，Vue 3配4.x），然后看路由初始化代码是不是对应版本的写法，要是版本错了，先把依赖改成匹配的（比如Vue 3项目里，把vue-router版本改成^4.0.0，再重新装依赖）；要是写法错了，按对应版本的官方示例改代码。

自定义history时，“自己写的逻辑漏了关键方法”

有些场景下，咱们需要自定义路由的history（比如做测试时mock路由行为，或者搞特殊的路由拦截逻辑），这时候如果自己实现的history对象没包含createHref方法，就会触发这个报错。

Vue Router对history对象的接口有明确要求，其中createHref的作用是“根据路由对象生成对应的URL字符串”，比如官方文档里，history对象至少得有这些关键方法：

createHref(route)：接收路由对象，返回URL字符串
push(location)：跳转路由
replace(location)：替换路由
listen(cb)：监听路由变化

举个错误的自定义例子（模拟测试时随便写的）：

// 错误示范：自定义history少了createHref
const myHistory = {
  push: (loc) => { /* 处理跳转 */ },
  replace: (loc) => { /* 处理替换 */ },
  listen: (cb) => { /* 监听变化 */ }
}
const router = createRouter({
  history: myHistory, // 这里传入的history没createHref
  routes: [...]
})

这时候路由内部调用history.createHref时，就会因为找不到这个方法报错，解决办法也简单：给自定义的history对象补上createHref方法，比如像这样：

// 正确示范：补上createHref
const myHistory = {
  push: (loc) => { /* 处理跳转 */ },
  replace: (loc) => { /* 处理替换 */ },
  listen: (cb) => { /* 监听变化 */ },
  createHref: (route) => { 
    // 根据route对象生成URL，比如简单拼接
    return `/${route.name || ''}` 
  }
}
const router = createRouter({
  history: myHistory,
  routes: [...]
})

要是你对自定义history的逻辑拿不准，建议先看Vue Router官方文档里的History接口定义，保证每个必要方法都实现到位。

框架自动生成路由，和手动配置“打架”了

现在很多Vue项目会用Nuxt.js、Quasar这些框架，它们本身自带路由自动生成逻辑，要是你手动去改路由配置，很容易和框架的默认逻辑冲突，导致history对象异常。

比如Nuxt.js的项目，它会根据pages目录自动生成路由，还内置了自己的history处理逻辑，要是你在项目里手动创建router.js，用createRouter重新初始化路由，就可能和Nuxt的自动路由系统“撞车”，让history对象的结构乱掉，进而出现createHref找不到的情况。

解决这类问题，核心思路是优先遵循框架的路由规则：

先查框架官方文档，看路由是自动生成还是需要手动配置，比如Nuxt.js里，除非有特殊需求（如自定义中间件、动态路由规则），否则不用自己写router实例；
如果必须手动调整路由，要按照框架提供的扩展方式来，比如Nuxt.js可以通过extendRoutes方法去修改自动生成的路由，而不是完全重写；
如果是Vue CLI或Vite创建的纯Vue项目，确认自己没装冲突的路由插件（比如同时用了vue-router和另一个路由库）。

举个实际案例：之前有同学在Nuxt项目里，觉得自动生成的路由不够灵活，就自己写了个router.js，结果页面一刷新就报createHref错误，后来发现Nuxt已经内置了路由，手动创建的router实例和框架内部的history逻辑冲突了，把自己写的router.js删掉，改用Nuxt的extendRoutes来扩展路由，问题就解决了。

依赖版本乱成粥，或者缓存在“搞鬼”

有时候项目里的依赖版本看似匹配，但实际因为node_modules缓存、锁文件（package-lock.json或yarn.lock）的问题，导致Vue和Vue Router版本暗中不兼容，要是项目里同时装了多个版本的vue-router，也会让代码执行时“找错对象”。

解决这类问题，可以按这几步来：

检查版本匹配：打开package.json，确认vue和vue-router的版本对应（Vue 2 → vue-router 3.x；Vue 3 → vue-router 4.x），要是版本对不上，先改package.json里的版本号；
清空依赖缓存：把node_modules文件夹删掉，再执行npm install（或yarn install）重新装依赖，如果是用pnpm，还可以加--force强制重新解析依赖；
检查锁文件：有时候package.json改了，但锁文件没更新，导致实际装的版本不对，可以删除package-lock.json（或yarn.lock）后再重新装依赖，让锁文件重新生成；
排查重复依赖：用npm ls vue-router（或yarn why vue-router）看看项目里是不是装了多个版本的vue-router，要是有，得把多余的版本去掉。

举个例子：之前有个项目，package.json里写的是vue-router@4，但因为yarn.lock里还留着3.x的版本，实际安装后node_modules里同时有3.x和4.x，代码运行时加载了旧版本的vue-router，结果用法是4.x的写法，自然就报错了，把yarn.lock删了重新装，问题就解决了。