Vite 插件

vitarx-router 提供了 Vite 插件，用于在 Vite 项目中集成基于文件系统的自动路由生成能力。插件内部基于 FileRouter 实现，负责虚拟模块、代码转换、热更新等 Vite 特有的集成工作。

VitarxRouter()

创建 Vitarx Router Vite 插件实例。

类型定义

/**
 * 创建 Vitarx Router Vite 插件
 * @param options - 插件配置选项，继承自 FileRouterOptions
 * @returns Vite 插件实例
 */
function VitarxRouter(options?: RouterPluginOptions): Plugin

参数

参数	类型	默认值	说明
options	`RouterPluginOptions`	`{}`	插件配置选项，继承自 `FileRouterOptions`

RouterPluginOptions 继承 FileRouterOptions 的全部属性，未添加额外的 Vite 特有配置项。详见 FileRouterOptions。

返回值

类型	说明
`Plugin`	Vite 插件实例

虚拟模块

插件通过虚拟模块 virtual:vitarx-router:routes 提供自动生成的路由配置。在代码中通过以下方式导入使用：

// 导入自动生成的路由配置
import { routes, handleHotUpdate } from 'vitarx-router/auto-routes'

导出内容：

导出项	类型	说明
`routes`	`Route[]`	自动生成的路由配置数组
`handleHotUpdate`	`(router, callback?) => void`	热更新处理函数

插件生命周期

钩子	说明
`config`	识别是否为预览模式，预览模式下不执行任何操作
`configResolved`	创建 `FileRouter` 实例，初始化路由扫描
`resolveId`	解析虚拟模块 ID，将 `virtual:vitarx-router:routes` 映射为内部 ID
`load`	加载虚拟模块内容，调用 `FileRouter.generate()` 生成路由代码
`transform`	转换页面文件代码，移除 `definePage` 宏调用
`configureServer`	配置开发服务器文件监听，实现热更新
`closeBundle`	清理文件监听器和路由管理器实例，防止内存泄漏

热更新机制

开发模式下，插件会监听页面目录的文件变化：

文件变化事件通过批量节流处理（默认 100ms），同一文件的多次变更会被合并
调用 FileRouter.handleChange() 判断是否影响路由
路由变更时使虚拟模块缓存失效，并向依赖该模块的物理文件发送 HMR 更新信号
客户端通过 handleHotUpdate() 接收更新并刷新路由表

示例

基本用法

// vite.config.ts
import VitarxRouter from 'vitarx-router/vite'

export default defineConfig({
  plugins: [
    VitarxRouter({
      pages: 'src/pages',
      pathStrategy: 'kebab',
      dts: 'typed-router.d.ts'
    })
  ]
})

完整项目集成

// vite.config.ts
import VitarxRouter from 'vitarx-router/vite'

export default defineConfig({
  plugins: [
    VitarxRouter({
      pages: 'src/pages',
      pathStrategy: 'kebab',
      importMode: 'lazy',
      dts: 'typed-router.d.ts',
      extendRoute(route) {
        // 为所有路由添加默认 meta
        route.meta ??= { auth: false }
      }
    })
  ]
})

// src/main.ts
import { createRouter } from 'vitarx-router'
import { routes, handleHotUpdate } from 'vitarx-router/auto-routes'

const router = createRouter({ routes })

// 开发模式下启用热更新
if (import.meta.hot) {
  handleHotUpdate(router)
}

多页面目录

// vite.config.ts
import VitarxRouter from 'vitarx-router/vite'

export default defineConfig({
  plugins: [
    VitarxRouter({
      pages: [
        { dir: 'src/pages', prefix: '' },
        { dir: 'src/docs', prefix: '/docs', group: true }
      ],
      dts: true
    })
  ]
})

自定义导入模式

// vite.config.ts
import VitarxRouter from 'vitarx-router/vite'

export default defineConfig({
  plugins: [
    VitarxRouter({
      pages: 'src/pages',
      importMode(context) {
        // 对管理后台页面使用同步加载
        if (context.filePath.includes('/admin/')) {
          return 'sync'
        }
        return 'lazy'
      }
    })
  ]
})

相关：FileRouter API | 文件系统路由指南

handleHotUpdate()

路由热更新处理函数。在开发模式下监听路由配置变化，动态更新路由表。

类型定义

function handleHotUpdate(router: Router, onRoutesUpdated?: (routes: Route[]) => void): void

参数

参数	类型	说明
router	`Router`	路由器实例
onRoutesUpdated	`(routes: Route[]) => void`	路由更新后的回调函数，接收新的路由数组

详情

handleHotUpdate() 通过 import.meta.hot.accept() 监听虚拟模块 virtual:vitarx-router:routes 的变化。当页面文件发生增删改时，Vite 插件会自动重新生成路由配置，此函数接收更新后的路由并刷新路由表。

热更新流程：

接收新的路由模块
清空当前路由表
逐条添加新路由
调用 onRoutesUpdated 回调（如有）
重新匹配当前路由，更新 meta 信息
如果当前路由不再匹配，自动刷新页面

示例

import { createRouter } from 'vitarx-router'
import { routes, handleHotUpdate } from 'vitarx-router/auto-routes'

const router = createRouter({ routes })

// 基本用法
if (import.meta.hot) {
  handleHotUpdate(router)
}

// 带回调的热更新
function addRedirects() {
  router.addRoute({
    path: '/new-about',
    redirect: '/about'
  })
}

if (import.meta.hot) {
  handleHotUpdate(router, () => {
    // 路由更新后重新添加动态路由
    addRedirects()
  })
} else {
  addRedirects()
}