前言
大家好，我是 笨笨狗吞噬者，uni-app、varlet、nrm 等众多知名仓库的核心开发，专注于分享前端技术和 AI实践知识，本篇文章是 uni-app 小程序源码解读的第一期，欢迎关注我的微信公众号 前端笨笨狗！
很多人在使用 uni-app 时，会很自然地写出 uni.showToast()、uni.login() 这样的代码，但很少会继续追问一个问题：为什么同样是 uni.xxx，到了微信能落到 wx.xxx，到了支付宝又能落到 my.xxx？
这个问题背后，藏着一个巧妙的设计思路。它既不是简单的字符串替换，也不是把所有平台 API 硬编码映射一遍，接下来我们慢慢揭秘。
问题背景
在 uni-app 小程序端，开发者写的是：
uni.showToast({ title: 'Hello' })
uni.login()
但真正运行时：
- 微信里调用的是
wx.xxx
- 支付宝里调用的是
my.xxx
这一层统一，核心就靠两样东西：
-
Proxy：决定 uni.xxx 这次到底取哪个实现
-
wrapper：把不同平台之间的参数、方法名、返回值差异包起来
对应源码入口在 https://github.com/dcloudio/uni-app/blob/uni-app-vue3-dev/packages/uni-mp-core/src/api/index.ts#L61。
Proxy：统一入口分发
先看核心代码：
export function initUni(api, protocols, platform = __GLOBAL__) {
const wrapper = initWrapper(protocols)
const UniProxyHandlers = {
get(target, key) {
if (hasOwn(api, key)) {
return promisify(key, api[key])
}
if (hasOwn(baseApis, key)) {
return promisify(key, baseApis[key])
}
return promisify(key, wrapper(key, platform[key]))
},
}
return new Proxy({}, UniProxyHandlers)
}
这段代码的意思很简单：
uni 不是一个提前写死所有方法的对象，而是一个“访问属性时再决定返回什么”的代理对象。
比如你写：
uni.showToast
这时会触发 get(target, key)，其中：
-
key 就是 showToast
- 代理会临时判断这个方法应该从哪里来
也就是说，Proxy 的作用不是执行 API，而是做一次统一分发。
为什么这里一定要用 Proxy
因为 uni 的目标不是“绑定某个平台”，而是“对外提供稳定名字，对内按平台切换实现”。
如果不用 Proxy，那就只能：
- 提前把所有 API 全部挂到
uni 上
- 或者每个平台都维护一套映射逻辑
这样会很笨重。
用了 Proxy 之后，框架就可以做到：
- 开发者永远写
uni.xxx
- 真正访问到
uni.xxx 时，再动态决定用谁
- 同一个入口，底层可以切到不同平台对象
这正是代理最适合的场景：入口统一，底层实现可变。
这段 get 其实分了三层
源码里的分发顺序很清楚：
1. 先看 api
if (hasOwn(api, key)) {
return promisify(key, api[key])
}
如果这个方法 uni 自己实现过，就优先返回 uni 自己的实现。
2. 再看 baseApis
if (hasOwn(baseApis, key)) {
return promisify(key, baseApis[key])
}
像事件总线、拦截器这类基础能力，不一定来自小程序原生对象，也统一挂在 uni 上。
3. 最后兜底到平台对象
return promisify(key, wrapper(key, platform[key]))
这里的 platform 默认是 __GLOBAL__，可以理解成当前平台全局对象：
所以 Proxy 最终做成了这件事：
uni.showToast -> 当前平台的 showToast
uni.login -> 当前平台的 login
wrapper：翻译平台差异
如果只是：
return platform[key]
表面上也能调用，但问题是不同小程序平台并不完全一致，常见差异有三种：
- 方法名不一致
- 参数名不一致
- 返回值结构不一致
所以 Proxy 只能解决“分发给谁”，解决不了“怎么适配差异”。
这就是 wrapper 的职责。
wrapper 在这里干了什么
看最关键的一句：
const returnValue = __GLOBAL__[options.name || methodName].apply(
__GLOBAL__,
args
)
这里能看出两件事。
第一，wrapper 允许改方法名。
- 默认调用
methodName
- 如果协议里配置了
options.name，就改成另一个平台方法名
第二，wrapper 会先处理参数，再调用平台方法。
前面的 processArgs、后面的 processReturnValue，本质上都在做一件事：
把 uni 暴露给开发者的统一接口，翻译成当前平台真正认识的接口。
所以可以把 wrapper 理解成一个“翻译层”。
举一个最容易理解的例子
假设 uni 对外想统一成这样：
uni.showToast({
title: '保存成功'
})
但某个平台底层不是 title，而是 content。
那 Proxy 只能做到：
uni.showToast -> 找到这个平台的方法
真正把参数从：
{ title: '保存成功' }
改成：
{ content: '保存成功' }
这一步必须由 wrapper 做。
也就是说：
-
Proxy 负责“找到人”
-
wrapper 负责“翻译话”
这两个配合起来，开发者才能始终写统一的 uni.xxx。
简易实现
下面写一个极简版，只保留 Proxy 和 wrapper 两层核心思想。
const wx = {
showToast(options) {
console.log('wx.showToast', options)
},
}
function wrapper(name, method) {
if (name === 'showToast') {
return function (options) {
const newOptions = {
content: options.title,
}
return method(newOptions)
}
}
return method
}
function initUni(platform) {
return new Proxy(
{},
{
get(target, key) {
const method = platform[key]
if (typeof method !== 'function') {
return undefined
}
return wrapper(key, method)
},
}
)
}
const uni = initUni(wx)
uni.showToast({
title: '保存成功',
})
执行时虽然外部写的是：
uni.showToast({ title: '保存成功' })
但实际到平台方法时，已经被改成了：
wx.showToast({ content: '保存成功' })
总结
不是“用了 Proxy 很高级”，而是职责拆得很清楚：
-
Proxy 只做入口分发
-
wrapper 只做平台适配
这样设计的好处是：
-
uni 对开发者始终保持统一
- 平台差异被收口在框架内部
- 后续要支持更多小程序平台时，只需要补适配逻辑，不需要改开发者写法
微信交流群
我有个 uni-app 微信交流群，大家有想进群的可以加我的微信 13460036576
登录
