如何在Nuxt 3中扩展Router类型？解决Query类型报错问题

问题描述 #

使用嵌套对象结构的query参数时（示例如下），会触发类型错误：'Object literal may only specify known properties, and query does not exist in type NavigationGuardNextCallback'

示例query结构：

query: {
  filter: {
    name: string,
    age: number,
  },
  page: number,
  perPage: number,
}

解决方法 #

Nuxt 3的路由类型扩展逻辑和Vue 3略有区别，需要针对vue-router的核心类型进行扩展，具体操作如下：

1. 在项目根目录创建types/router.d.ts类型声明文件（Nuxt会自动识别该目录下的类型文件）
2. 写入以下代码，扩展自定义query类型及相关路由接口：

import type { RouteQuery } from 'vue-router'

declare module 'vue-router' {
  // 定义自定义Query结构
  interface CustomRouteQuery extends RouteQuery {
    filter?: {
      name?: string
      age?: number
    }
    page?: number
    perPage?: number
  }

  // 让RouteLocationRaw支持自定义Query
  interface RouteLocationRaw {
    query?: CustomRouteQuery
  }

  // 扩展导航守卫的next回调类型，适配自定义路由参数
  interface NavigationGuardNextCallback {
    (to?: RouteLocationRaw): void
  }
}

3. 若类型未自动生效，可在nuxt.config.ts中显式指定类型文件路径：

export default defineNuxtConfig({
  typescript: {
    include: ['types/**/*.d.ts']
  }
})

补充说明 #

不同于Vue 3中直接扩展Router接口的方式，Nuxt 3需要基于vue-router的RouteLocationRaw和NavigationGuardNextCallback进行扩展，以此让类型系统识别自定义的嵌套query结构，消除类型错误。

内容的提问来源于stack exchange，提问作者skav3n