代理的妙用：uni-app 小程序是怎样用 `Proxy` 和 `wrapper` 抹平平台差异的

前言

大家好，我是 笨笨狗吞噬者，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 之后，框架就可以做到：

1. 开发者永远写 uni.xxx
2. 真正访问到 uni.xxx 时，再动态决定用谁
3. 同一个入口，底层可以切到不同平台对象

这正是代理最适合的场景：入口统一，底层实现可变。

这段 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__，可以理解成当前平台全局对象：

• 微信环境下接近 wx
• 支付宝环境下接近 my

所以 Proxy 最终做成了这件事：

uni.showToast -> 当前平台的 showToast
uni.login -> 当前平台的 login

wrapper：翻译平台差异

如果只是：

return platform[key]

表面上也能调用，但问题是不同小程序平台并不完全一致，常见差异有三种：

1. 方法名不一致
2. 参数名不一致
3. 返回值结构不一致

所以 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