告别手写字符串！UniApp 路由全自动类型生成工具

71Ove
16 阅读3分钟

一、 开发背景与痛点

在进行 UniApp + TypeScript 开发时，路由跳转一直是一个让人头疼的问题。由于 UniApp 的路由定义在 pages.json 中，我们在代码里调用跳转 API 时，往往面临以下窘境：

  1. 纯手动输入：每次 uni.navigateTo 都要手动拼写路径字符串，不仅慢，还容易写错。
  2. 重构噩梦：一旦在 pages.json 中修改了页面路径，全局搜一遍字符串去改，极易遗漏引发线上 Bug。
  3. 无类型提示：IDE 无法感知哪些路径是合法的，跳转全靠“盲猜”。
  4. 分包路径复杂：主包、分包路径层级深，拼接字符串极其痛苦。

为了彻底解决这些 DX（开发者体验）痛点，我开发了 vite-plugin-uniapp-router-type 插件。

二、 插件初衷与目的

本插件的核心思路非常简单：让代码跑在配置前面。

通过监听 pages.json 的变化，插件会自动解析其中的 pages 和 subPackages 配置，并实时生成一份全量的路径类型声明文件。它能让你的跳转代码从“盲打”变成“点选”，极大地提升开发效率和代码健壮性。

三、 安装与配置

该插件仅在开发阶段用于辅助生成类型文件，因此建议安装为 开发依赖 (-D) 。

1. 安装插件

Bash

npm install vite-plugin-uniapp-router-type -D
# 或者使用 pnpm
pnpm add vite-plugin-uniapp-router-type -D

2. Vite 配置

在项目根目录的 vite.config.ts 中引入并添加到 plugins 数组中：

TypeScript

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import uniappRouterType from 'vite-plugin-uniapp-router-type';

export default defineConfig({
  plugins: [
    uni(),
    // 默认配置下，插件会读取 src/pages.json 并在 src/types/router.d.ts 生成类型
    uniappRouterType({
      // 可选配置 (默认值如下)
      // pagesJsonPath: 'src/pages.json', // pages.json 路径
      // outputDir: 'src/types',         // 类型定义输出目录
      // fileName: 'router.d.ts'         // 生成的文件名
    })
  ]
});

四、 功能示例

1. 丝滑的路径自动补全

由于插件自动增强了全局 Uni 接口的跳转方法，当你输入 / 时，IDE 会自动弹出所有在 pages.json 中定义过的合法路径：

TypeScript

// IDE 将自动提示所有合法路径
uni.navigateTo({
  url: '/pages/index/index?id=1' // 路径受到类型强约束，拼错会报错
});

// 同样支持 switchTab 的路径过滤
uni.switchTab({
  url: '/pages/tabbar/home' 
});

2. 手动引用导出的类型

如果你需要为组件的 Props 或自定义函数定义路由相关的类型，可以直接引用导出的 PagePath 或 PageUrl：

TypeScript

import type { PagePath, PageUrl } from '@/types/router';

// 仅代表纯路径
const myPath: PagePath = '/pages/user/info'; 

// 代表路径或带参数的 URL (例如: /pages/detail/index?id=123)
const myUrl: PageUrl = '/pages/detail/index?id=100';

五、 结语

vite-plugin-uniapp-router-type 现已开源并发布至 npm。它的初衷是让 UniApp 的开发也能拥有像 Web 路由那样的强类型保障。

如果这个插件能帮你在开发中少写两个 Bug，少熬两个夜，请给项目点个 Star 支持一下！

欢迎大家在评论区提出宝贵的意见，我会持续优化迭代。

avatar
文章
阅读
粉丝