uniapp-pages-router

高性能的 UniApp pages.json 解析插件，零依赖，支持 TypeScript。

uniapp-pages-router 是一个专为 UniApp 项目设计的构建时路由解析插件，能够自动解析 pages.json 配置文件，生成路由信息并注入到项目中，支持主包、分包和 TabBar 路由。自 1.0.0 起 API 已稳定，可用于生产环境。

特性

• 零依赖 - 内置 JSON 注释处理器，无外部依赖
• 路由映射 - 自动生成路由映射表，快速通过路径查找路由信息
• TabBar 支持 - 自动提取底部导航配置，生成映射表
• 路由校验 - 开发模式下检测重复路径、重复别名、无效 TabBar pagePath
• TypeScript - 完整的类型支持和智能提示
• 双格式 - 支持 ESM/CJS 双格式输出
• 分包支持 - 完整支持 UniApp 分包路由解析

安装

npm install -D uniapp-pages-router

pnpm add -D uniapp-pages-router

yarn add -D uniapp-pages-router

bun add -D uniapp-pages-router

快速开始

1. 配置 Vite

CLI 项目

// vite.config.ts
import { defineConfig } from "vite";
import { resolve } from "path";
import { uniRouter } from "uniapp-pages-router";

export default defineConfig({
  plugins: [
    uniRouter({
      pages: resolve(__dirname, "./src/pages.json"),
      fields: ["meta", "style"],
    }),
  ],
});

HBuilderX 项目

// vite.config.ts
import { defineConfig } from "vite";
import { resolve } from "path";
import { uniRouter } from "uniapp-pages-router";

export default defineConfig({
  plugins: [
    uniRouter({
      pages: resolve(__dirname, "./pages.json"),
      fields: ["meta", "style"],
    }),
  ],
});

2. TypeScript 类型声明

在 tsconfig.json 中引用全局类型（推荐）：

{
  "compilerOptions": {
    "types": ["uniapp-pages-router/global"]
  }
}

或在项目中创建 types/env.d.ts：

/// <reference types="uniapp-pages-router/global" />

也可以从包中导入类型，自行声明全局变量：

import type { RouteItem, RouteMap, TabBarMap } from "uniapp-pages-router";

declare const UNI_ROUTES: RouteItem[];
declare const UNI_ROUTE_MAP: RouteMap;
declare const UNI_TABBAR_ROUTES: string[];
declare const UNI_TABBAR_MAP: TabBarMap;

3. 在代码中使用

// 获取所有路由信息
console.log("所有路由:", UNI_ROUTES);

// 通过路径快速查找路由
const route = UNI_ROUTE_MAP["/pages/index/index"];

// 判断是否为 TabBar 页面
if (UNI_TABBAR_MAP[page]) {
  uni.switchTab({ url: page });
}

// 获取 TabBar 路由列表
console.log("TabBar 路由:", UNI_TABBAR_ROUTES);

配置选项

interface Options {
  /** pages.json 文件路径 */
  pages: string;
  /** 需要额外提取的字段，默认包含 'path' 和 'alias' */
  fields?: string[];
}

配置示例

uniRouter({
  pages: "./pages.json",
  fields: ["meta", "style", "needLogin"],
});

数据结构

路由项 (RouteItem)

import type { RouteItem, RouteMap, TabBarMap } from "uniapp-pages-router";

RouteItem 包含 path、alias 及通过 fields 配置的任意自定义字段。

全局变量

| 变量名 | 类型 | 描述 | | ------------------- | --------------------------- | ----------------------------- | | UNI_ROUTES | RouteItem[] | 所有路由信息数组 | | UNI_ROUTE_MAP | Record<string, RouteItem> | 路由映射表，key 为路径 | | UNI_TABBAR_ROUTES | string[] | TabBar 页面路径数组 | | UNI_TABBAR_MAP | Record<string, true> | TabBar 映射表，用于 O(1) 判断 |

应用场景

路由守卫

function checkAuth(path: string): boolean {
  const route = UNI_ROUTE_MAP[path];
  return !route?.needLogin || isLoggedIn();
}

TabBar 判断

// O(1) 查找
if (UNI_TABBAR_MAP[page]) {
  uni.switchTab({ url: page });
}

pages.json 示例

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      },
      "meta": {
        "title": "首页",
        "icon": "home"
      }
    }
  ],
  "subPackages": [
    {
      "root": "pages-sub",
      "pages": [
        {
          "path": "detail/detail",
          "style": {
            "navigationBarTitleText": "详情页"
          }
        }
      ]
    }
  ],
  "tabBar": {
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/profile/profile", "text": "我的" }
    ]
  }
}

更新日志

详见 CHANGELOG.md。

License

MIT License