onLoad是唯一可靠入口,因uni-app未集成Vue Router,this.$route不存在;options由框架在页面加载时注入,setup/onMounted中无法访问,且参数全为字符串需手动转换。

onLoad 是唯一可靠入口,其他方式(如 setup、onMounted、this.$route)在 uni-app 中拿不到路由参数。
为什么必须用 onLoad?
uni-app 的页面生命周期与小程序原生机制对齐:onLoad 是页面加载时第一个被触发的钩子,且此时 options 参数已由框架注入。Vue3 组合式 API 中不能在 setup 里直接访问路由参数,useRoute 不可用,this.$route 也不存在——uni-app 没有集成 Vue Router。
常见错误现象:
- 在
onMounted里读options→ 得到undefined - 用
defineProps声明id: string→ 编译不报错但运行时无值(props 不接收 URL 参数) - 在
setup里调用getCurrentPages()→ 可能取到上一页,但当前页options还没准备好
onLoad 怎么写才不出错?
Vue2 选项式和 Vue3 组合式写法都支持,但签名和位置有差异:
- Vue2:直接写在
export default { onLoad(options) { ... } }里 - Vue3:必须用
onLoad((options) => { ... }),放在setup外部或onLoad导入后调用 -
options是 plain object,所有字段都是字符串,哪怕 URL 里写的是?id=123&active=true,拿到的也是{ id: "123", active: "true" }
示例(Vue3):
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
import { onLoad } from '@dcloudio/uni-app'
onLoad((options) => {
const id = parseInt(options.id) || 0
const active = options.active === 'true'
console.log({ id, active })
})
参数类型转换容易漏掉什么?
URL 参数全为字符串,不做显式转换会埋坑:
-
parseInt(options.count)遇到空值或非数字会返回NaN,建议加|| 0或用Number()+isNaN()判断 -
options.flag === 'true'才算布尔真,'1'、'yes'、空字符串都不能直接当 boolean 用 - JSON 字符串(如
?user=%7B%22name%22%3A%22tom%22%7D)必须先decodeURIComponent再JSON.parse,缺一不可 - 中文或特殊字符未编码时,
options可能缺失字段,控制台看不到报错,只发现某个 key 是undefined
调试时 options 是空对象怎么办?
不是代码写错了,大概率是跳转 URL 本身有问题:
- 拼接 URL 时漏了
?或用了&却没转义(应写作&或直接用&) - H5 端刷新页面后,
onLoad不再触发,options为空 —— 这是预期行为,需改用uni.getStorageSync或路由守卫类方案补位 - 使用
uni.reLaunch或从 TabBar 进入页面时,onLoad仍会触发,但options一定为空,因为不是“带参跳转”产生的 - 组件式跳转(
)中:url绑定未加引号或表达式出错,导致最终渲染的 url 是/pages/detail?id=这种残缺形态
最稳的验证方式:在跳转前 console.log 出完整 url 字符串,粘贴进浏览器地址栏看能否正常解析。









