更新记录

1.1.0（2026-10-16） 下载此版本

• 增加全局和单路由模糊公开路径配置。
• 支持大小写、连字符、下划线和驼峰形式的公开路径识别。
• 模糊地址命中后自动规范化为唯一公开地址。
• 修正 H5 vue-router history 包装和 HBuilderX 项目根目录解析。

平台兼容性

uni-app(3.8.6)

uni-app H5 路由别名与 URL 美化

aw-pretty-route 是一款适用于 uni-app Vue 3 + Vite 的 H5 路由别名与 URL 美化插件。它可以把 pages.json 中的真实页面路径转换为简洁、稳定、适合分享和 SEO 的公开 URL，同时支持动态路径参数、query 参数映射，以及大小写、蛇形和驼峰路径兼容。

业务代码继续使用 uni-app 注册的真实路径，H5 地址栏自动显示公开路径；App 和小程序保持原生页面路径，不需要修改业务跳转代码。

适用场景

能力总览

接入方式

1. 注册 Vite 插件

// vite.config.js
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { createAwPrettyRoutePlugin } from './uni_modules/aw-pretty-route/js_sdk/vite.js'

export default defineConfig({
  plugins: [createAwPrettyRoutePlugin(), uni()]
})

只需要配置一次，不需要在 main.js 安装运行时插件。

2. 页面正常注册

{
  "path": "pages/product/site",
  "routeAlias": "/product"
}

3. 业务继续使用真实路径

uni.navigateTo({
  url: '/pages/article/detail?id=123'
})

真实路径和公开路径

插件同时维护两种路径：

public 不是文件路径，也不是 pages.json 中的页面路径。它只是希望用户在 H5 地址栏看到的 URL 模板。

例如：

业务跳转：/pages/article/detail?id=123
H5 地址栏：/article/123

业务代码仍然传真实路径：

uni.navigateTo({
  url: '/pages/article/detail?id=123'
})

路径行为

全局配置

在项目根目录创建 aw-pretty-route.config.js：

export default {
  home: '/pages/index/index',
  fuzzy: true,
  routes: [
    {
      // 必须是 pages.json 中已经注册的页面路径。
      real: '/pages/article/detail',
      // H5 地址栏显示的公开 URL，:id 是路径参数。
      public: '/article/:id(\\d+)',
      // 从真实页面 query 中读取路径参数。
      params: { id: 'query.id' }
    }
  ]
}

单路由配置

在 pages.json 中配置静态页面

{
  "path": "pages/private/index",
  "routeAlias": "/private",
  "routeFuzzy": false
}

在动态规则中配置

{
  // pages.json 中注册的真实页面路径。
  real: '/pages/article/detail',
  // H5 地址栏使用的公开 URL 模板。
  public: '/article/:id',
  // :id 从 query.id 中取值。
  params: { id: 'query.id' },
  fuzzy: false
}

模糊路径规则

开启 fuzzy 后，以下写法可以指向 /product-center：

/product-center
/ProductCenter
/product_center
/PRODUCT-CENTER

命中后地址栏统一为 /product。模糊路径只用于兼容识别，不会产生多个正式公开 URL。

如果多个启用模糊匹配的路由归一化后冲突，构建阶段会报错。

URL API

只在分享、复制链接、SEO canonical 或普通 <a> 链接等场景使用：

import { getPublicUrl } from './uni_modules/aw-pretty-route/js_sdk/index.js'

const url = getPublicUrl('/pages/article/detail?id=123')

日常 navigateTo、redirectTo、reLaunch 和 switchTab 不需要调用这些 API。

params 参数映射

params 的左侧是公开路径中的参数名，右侧是 uni-app 真实页面 URL 中的 query 参数来源。

{
  real: '/pages/article/detail',
  public: '/article/:id',
  params: {
    id: 'query.id'
  }
}

转换关系如下：

真实页面 URL：/pages/article/detail?id=123&tab=comments
公开页面 URL：/article/123?tab=comments

其中：

平台和部署

H5 使用 history 模式，生产服务器必须把未知路径回退到 index.html。

常见问题