企业官网建设流程全解析

微信小程序开发这个系列写到第4章，终于要碰一个绕不开的话题：小程序API。前面几章我们把页面、组件、样式这些基础折腾得差不多了，但从这一刻开始，你会发现小程序真正的价值不是写界面，而是通过wx.xxx这一堆API去调用系统能力，再跟自己的后端做数据交换。这篇文章我会从小程序API的设计规则讲起，覆盖请求封装、缓存、导航栏、返回拦截、视频下载、地图、蓝牙、支付这些高频场景，最后把那些让人崩溃的报错和iOS网络问题挨个扒一遍。适合刚入门小程序开发、以及对API用法不系统的新手，也适合那些想把手头项目里“能用但很乱”的API调用整理一遍的同学。

1. 小程序API的设计哲学：为什么每个接口都长这样

1.1 从wx.xxx说起：全局对象与异步回调

第一次打开微信开发者工具，看到wx.login、wx.request、wx.getStorageSync这一堆接口的时候，很多人是懵的。其实逻辑特别简单：微信把手机上的系统能力和微信自身的能力全部挂在wx这个全局对象下面，你要用定位调wx.getLocation，要发请求调wx.request，要弹一个提示调wx.showToast，全部都是这一个命名空间下的方法。所以当你听到“小程序API”这个词，就可以直接理解成“wx对象上那些可以用来自造功能的方法集合”。

为什么这些方法几乎都是异步回调而不是同步返回？我举个生活里的例子：你让室友下楼取快递，你不能站在门口干等他回来才继续干自己的事，而是会跟他说“取到了微信我一声”，然后该干嘛干嘛。小程序API也是一样的道理，比如wx.request发一个网络请求，底层要建立连接、等服务器响应，这个过程是几百毫秒甚至更久，不可能让主线程卡在那里等结果回来。所以微信设计了success、fail、complete三兄弟：success是拿快递成功了回来告诉你，fail是下楼摔了一跤没取到，complete是无论成没成都要回来说一声，适合放关闭loading这一类收尾动作。

需要提醒的是，从基础库2.10.2开始，部分API也支持Promise写法，比如wx.request、wx.login这些高频接口可以直接用await。不过实际项目里我建议还是做一层统一的promisify封装，因为老版本基础库和一些冷门API并不支持Promise，你没法保证所有用户微信都是最新版。一个常见的兼容封装是这样的：

function promisify(api) { return (options = {}) => new Promise((resolve, reject) => { api({ ...options, success: resolve, fail: reject, }); }); }

用的时候把wx.request传进去：const requestAsync = promisify(wx.request)，之后就能用.then或者async/await写了。这里有个细节：success回调返回的对象里，网络层的数据在res.data，而HTTP状态码在res.statusCode，很多新手把res.data和res.statusCode搞混，导致明明返回了401却还在用res.data里面的业务code判断，这个在封装的拦截器里要尤其注意区分。

1.2 scope权限体系：一次授权背后发生了什么

很多人在新版基础库上直接调用wx.getUserProfile或者用button的open-type想拿用户头像昵称，结果控制台甩出来一个特别长的报错：chooseavatar:fail api scope is not declared in the private。这个报错在最近是个高频搜索词，其实它背后是微信隐私政策的调整。从2022年下半年开始，涉及用户隐私的接口（头像、昵称、位置、相册、麦克风、摄像头等）都必须在「小程序管理后台-设置-服务内容声明-用户隐私保护指引」里提前声明，声明范围要和代码里实际使用的接口匹配，否则调用时直接拒绝，根本走不到授权弹窗那一步。

我第一次遇到这个报错的时候以为是基础库版本太低，查了半天发现是后台配置漏了。所以当你看到api scope is not declared时，优先去检查三件事：第一，小程序管理后台的隐私保护指引有没有添加wx.chooseAvatar、wx.getLocation这一类接口；第二，添加之后有没有重新提交审核并发布一个版本；第三，代码里有没有在调用敏感接口前使用wx.requirePrivacyAuthorize主动确认。这里我踩过的坑是：后台配置了隐私接口，也发布了版本，但同事的小程序仍然是旧版本，隐私接口调用依然会失败，原因是隐私协议更新后用户端需要重新授权，得在页面上加一个隐私弹窗引导用户同意，很多团队忽略了这一步。

还有一点必须说清楚：为什么现在头像昵称获取不能直接一下拿全？微信调整后的方案是，头像要通过button的open-type="chooseAvatar"让用户主动点击选择，然后从e.detail.avatarUrl拿到临时头像路径，昵称要用input组件的type="nickname"让用户填写。这样设计的目的就是强制开发者最小化收集用户数据，避免后台静默就拿走了用户的完整资料。这是“用户主动触发才能调API”的典型场景，类似的情况还有录音、拍照这些能力，都必须由用户点击行为直接触发，不能在页面onLoad里偷偷调。

2. 请求、缓存与登录：小程序的网络基建

2.1 请求封装：wx.request的坑与封装思路

wx.request是小程序里每天打交道最多的API，没有之一。但原生用法其实挺原始的：没有拦截器、没有统一超时管理、默认不带Cookie、每次都要手动往header里塞token，而且同一个小程序并发请求上限是10个，超过之后请求会排队甚至被丢弃。所以我几乎没见过哪个正经项目是直接白板调用wx.request的，大家都会做一层封装。

我习惯把封装拆成几层：第一层是基础配置，包括baseURL、默认超时时间（小程序wx.request超时默认是60秒，这个对用户体验来说太长了，一般压到10到15秒）、公共header；第二层是拦截器，请求发出前注入token和content-type，响应回来后统一解包；第三层是错误处理，网络错误、401登录过期、业务code非0，每一种情况都有统一的处理逻辑，不让业务页面到处写try catch。

给你一个我能直接跑的简化版封装轮廓：

const request = (path, options = {}) => { const token = wx.getStorageSync('token'); return new Promise((resolve, reject) => { wx.request({ url: `${BASE_URL}${path}`, method: options.method || 'GET', data: options.data || {}, timeout: options.timeout || 15000, header: { 'Content-Type': 'application/json', Authorization: token ? `Bearer ${token}` : '', ...options.header, }, success: (res) => { if (res.statusCode === 401) { // 触发重新登录，然后重放请求 handleTokenExpired(); return; } if (res.statusCode >= 200 && res.statusCode < 300) { resolve(res.data); } else { reject(res); } }, fail: reject, }); }); };

这里想特别提醒一个域名问题：小程序里请求的URL必须在小程序管理后台配置request合法域名，而且必须是https，上线前如果你发现请求发不出去，第一反应不要是查代码，先去后台看域名配了没有。开发模式下可以在开发者工具右上角详情里勾选“不校验合法域名”，但那只适合本地调试，千万别带着这个设置交付。

2.2 缓存时间设置：带过期时间的缓存工具

热搜里有“微信小程序设置缓存时间”，这个问题其实是个高频需求。wx.setStorageSync这个API本身是不带过期机制的，它就是一个纯粹的本地存储，你把一个对象扔进去，它就永远放在那里，直到你自己removeStorageSync或者用户清缓存。很多业务场景是：首页配置想缓存5分钟、用户设置想缓存一天、广告位素材想缓存到明天。这时候就需要自己动手做一个带过期时间的缓存工具。

原理很简单：写入的时候在value里面附加一个expire时间戳，读取的时候先判断当前时间是否已经超过这个时间戳，超了就直接当没有这个缓存，顺手删掉。下面这个就是我在项目里一直用的简化版：

const PREFIX = 'cache_'; function setCache(key, data, expire = 5 * 60 * 1000) { const now = Date.now(); wx.setStorageSync(PREFIX + key, { data, expire: now + expire, }); } function getCache(key) { const raw = wx.getStorageSync(PREFIX + key); if (!raw) return null; if (Date.now() > raw.expire) { wx.removeStorageSync(PREFIX + key); return null; } return raw.data; }

用的时候setCache('home_config', config, 10 * 60 * 1000)，10分钟内反复进入首页就读缓存，超过10分钟自动失效重新请求。这个看起来很简单，但实际项目里有个容易忽略的坑：缓存失效之后不能无脑重新请求，因为用户看到的页面可能已经被缓存数据渲染过一次了，再请求新数据回来时如何跟旧数据做diff、怎么保证UI不闪烁，都需要在设计时想清楚。我一般会在缓存数据里加一个version字段，和后端下发的version对比，不一致再拉取新数据，这样既能省流量又能保证新鲜度。

还有存储空间问题：wx.setStorageSync单键数据上限1MB，整个小程序本地缓存总上限是10MB，超出后写入会失败。所以不要把图片base64、大日志往storage里塞，这种数据应该走文件系统，用wx.getFileSystemManager().writeFile写到本地用户文件目录。

2.3 登录态与token刷新：wx.login到底解决什么问题

wx.login拿到的code本身不是身份凭证，它只是给后端换用户身份用的“一次性暗号”。整个流程是：前端调wx.login拿到code，把code发给自己的后端，后端拿着code去微信服务器换openid和session_key，然后生成一个自己的业务token返回给前端，前端把这个token存下来，后续每个请求带在header里。

这个流程里最容易踩的坑是，有人以为wx.login返回的东西可以直接当用户信息用，直接把code存在本地，下次请求还用它。实际上code的有效期只有5分钟，而且只能用一次，第二次再拿这个code去换就是无效的。另外session_key是会话密钥，它应该留在后端，用来解密用户手机号、敏感数据，绝对不能下发到前端，否则一旦泄露，别人就能伪造用户身份。

还有一个我在项目里优化过的问题是：不要每次进入小程序都调wx.login。如果有有效token，直接用它请求业务接口就行；只有当发现token过期或请求返回401时，才触发静默重新登录。这个触发动作要设计成单例，避免多个并发请求同时检测到401然后同时调wx.login，搞得后端收到一堆重复的code换token请求。可以维护一个pendingLoginPromise，如果有登录请求在飞，其他请求就复用同一个Promise：

let loginPromise = null; function ensureLogin() { if (loginPromise) return loginPromise; loginPromise = new Promise((resolve, reject) => { wx.login({ success: async (res) => { const token = await requestToken(res.code); wx.setStorageSync('token', token); resolve(token); }, fail: reject, }).finally(() => { loginPromise = null; }); }); return loginPromise; }

3. 界面与交互API：从导航栏到返回拦截

3.1 顶部导航栏高度计算与自定义导航

自定义导航是做过小程序的人都会遇到的需求：默认导航栏样式太死板，想做成跟品牌色一致、左边带自定义图标、中间标题改成图片，就必须把navigationStyle改成custom，然后自己画一个导航栏。这里面最麻烦的不是画UI，而是“顶部状态栏高度到底是多少”这个问题。iPhone有刘海屏有灵动岛，安卓从4.4到现在的各种挖孔屏，状态栏高度千奇百怪，绝对不能写死。

正确算法依赖于两个API：wx.getWindowInfo()（旧版本是wx.getSystemInfoSync，已经被标记废弃）能拿到statusBarHeight状态栏高度；wx.getMenuButtonBoundingClientRect()能拿到右上角胶囊按钮的位置信息，包括它的top和height。微信官方给出的经验公式是：导航栏总高度 = 状态栏高度 + 胶囊按钮高度 + 胶囊按钮顶部到状态栏底部的间隙。用代码表示大概是这样：

const windowInfo = wx.getWindowInfo(); const menuRect = wx.getMenuButtonBoundingClientRect(); const navBarHeight = windowInfo.statusBarHeight + menuRect.height + (menuRect.top - windowInfo.statusBarHeight) * 2;

你可能会问为什么要乘以2，其实间隙是上下对称的，胶囊顶部到状态栏底部的距离，基本等于胶囊底部到导航栏底部的距离，所以导航栏总高度就是状态栏高度加上两倍的间隙再加胶囊高度。我第一次做的时候没乘，结果标题文字明显偏上，看着特别扭。每次启动时算一次，存到globalData里，后面所有页面直接引用，不要在页面里反复计算。这个算法在Android和iOS上实测都很稳，唯一要注意的是非常老的基础库可能拿不到menuRect，需要做降级处理，比如给一个默认高度44。

3.2 返回拦截：如何阻止用户误触返回

小程序默认左上角的返回按钮是由微信框架自己管理的，开发者无法直接监听“用户点了返回”。但有些场景确实需要拦截：编辑页面有未保存的内容、答题做到一半用户想退出、支付过程中防止误触返回导致流程中断。这种需求怎么做？我整理过三个方案。

第一个是官方方案：wx.enableAlertBeforeUnload，在页面onLoad里调用，开启后用户离开页面时会弹一个系统确认框，询问是否确认离开。它的优点是简单，不需要自定义导航栏，缺点是样式固定，只有一个框架提供的确认取消框，文案只能通过message参数改一部分，不支持自定义样式。第二个方案是自定义导航：把navigationStyle改成custom之后，返回按钮变成自己画的，点击时先用wx.showModal弹自定义提示，用户确认后再调wx.navigateBack。这个方案灵活，但要兼顾各种机型，自己算返回按钮的位置。第三个方案是重写页面栈方法，比如重写wx.navigateBack或劫持onUnload，但这个做法依赖内部实现，基础库一升级可能就失效，而且容易被审核盯上，我不太推荐再用了。

实际项目里我建议优先用wx.enableAlertBeforeUnload，它已经能满足绝大多数“离开前提醒”的需求。我踩过的一个坑是：这个API在某些安卓机型上，当用户点击右上角胶囊里的“关闭小程序”时不一定生效，所以如果你有极其严格的流程要求，还是得结合自定义导航来控制返回按钮，同时做好异常流程的后端兜底。

4. 常见业务场景API实录

4.1 视频下载与保存到相册

小程序里“视频下载”不是靠一个API直接打包完成的，它是一套组合拳：先通过wx.downloadFile把远程视频下载到本地临时文件，再通过wx.saveVideoToPhotosAlbum把临时文件保存到用户相册。这两个API分开看都不复杂，但组合起来坑不少。

第一个坑是域名白名单：下载视频的URL必须配置在后台的downloadFile合法域名里，否则downloadFile直接返回fail。第二个坑是授权：wx.saveVideoToPhotosAlbum需要用户授权保存到相册的能力（scope.writePhotosAlbum），如果用户之前拒绝过，再次调用会失败。这时候应该引导用户到设置页打开权限：wx.showModal提示“需要保存视频到相册”，用户确认后调wx.openSetting，让用户在小程序设置页里手动打开相册权限。我遇到过用户拒绝一次之后再也不弹授权框的情况，所以代码里既要处理fail又要处理scope被拒绝的情况，不能只是弹个toast就完了。第三个坑是临时文件和本地文件的区别：wx.downloadFile下载完的文件默认是临时文件，小程序重启后可能被清理。如果这个视频用户会反复看，建议再用wx.getFileSystemManager().saveFile把临时文件转存到本地用户目录，下次直接读本地路径，省流量也省时间。

版权问题还是要提一句：只能下载自己有权限的视频资源，不要拿这个能力去下载平台上别人的视频，审核和合规风险都不小。

4.2 地图、定位与天地图适配

位置和地图是另一个API重灾区，尤其是想做“景区票务与车位联动预约”“旅游系统”“生鲜配送”这类跟地理强相关的产品时。小程序里定位用wx.getLocation，它返回经纬度，包装一下还能拿到速度、方向的原始数据。但这个接口在后台必须声明位置用途，而且调用前会弹授权框，用户拒绝之后没有二次弹窗，只能引导去openSetting打开。另外，wx.getLocation返回的是WGS-84坐标系还是GCJ-02坐标系，这是很多人忽略的问题。微信默认返回的是gcj02（也就是国测局加密坐标），如果直接把这个坐标丢给天地图或者一些外国的地图服务，会出现几百米甚至更远的偏移。使用天地图或者其他国内地图服务时，要搞清楚对方接受什么坐标系，必要的时候做坐标转换。

热词里提到“uniapp接入天地图适配微信小程序、h5、app”。这块实际做起来比较蛋疼：天地图提供的是瓦片服务和一些地图API，但它不是微信小程序内置的地图服务商。微信小程序的map组件默认支持腾讯地图等几个源，要接入天地图通常有两条路：一条是用map组件拉天地图的瓦片图层，但这需要组件本身支持自定义图层类型，而且不同端的支持情况不一致；另一条是直接用web-view把天地图的网页版嵌入进来，但web-view在小程序里有很多限制：域名必须业务域名且校验ICP备案、交互能力有限、体验也不如原生map顺滑。我的经验是：如果只是展示地图和标记点，优先用微信map组件做，并在服务端把坐标系统一处理成组件能接受的格式；如果一定要天地图本身的底图风格或者天地图独有的图层数据，再考虑web-view方案，并且提前跟客户说清楚体验上的折损。

4.3 蓝牙、MQTT与硬件控制类API

物联网是小程序一个非常独特的使用场景，蓝牙和MQTT相关的问题在很多社区里讨论度都很高，比如“blufi微信小程序”“导入mqtt.js”这两个热词。乐鑫的Blufi是一个通过蓝牙给WiFi设备配网的协议，在小程序里要实现它，得走一遍完整的蓝牙流程：wx.openBluetoothAdapter打开蓝牙适配器、wx.startBluetoothDevicesDiscovery扫描设备、找到目标设备后wx.createBLEConnection建立连接、再通过wx.getBLEDeviceServices获取服务、wx.getBLEDeviceCharacteristics获取特征值，最后用wx.writeBLECharacteristicValue和wx.notifyBLECharacteristicValueChange做数据的发送和接收。这一整套流程写起来很繁琐，而且蓝牙API的错误码特别多，比如设备已连接、连接超时、特征值不支持写等等，每一步都要做状态机管理。

如果你用MQTT做数据通道，就需要引入mqtt.js。但这里有个大坑：小程序没有Node.js的net模块，所以mqtt.js默认的TCP连接不可用，必须使用它基于WebSocket的版本，而且连接地址要用wss开头。因为小程序对WebSocket连接有并发限制，切后台后socket会被系统挂起，所以一定要设计心跳检测和断线重连机制。我做过的一个设备配网项目里，遇到最多的问题是Android和iOS在扫描蓝牙设备时的表现不一样，Android返回的设备信息更完整，某些iPhone型号需要先打开系统定位服务才能扫描到蓝牙设备，这个坑不自己踩一遍绝对想不到。

4.4 支付与虚拟支付合规设计

关于支付的热词特别多，包括“虚拟支付苹果iap退款”“uniapp打包app支付和微信小程序支付时支付流程和参数是否相同”“微信小程序可以加入支付宝支付渠道吗”这些问题。先把结论说清楚：小程序内的支付只能走微信支付，通过wx.requestPayment拉起收银台。wx.requestPayment需要的timeStamp、nonceStr、package、signType、paySign这几个参数，必须由后端统一下单接口返回，前端不能自己算签名，也绝对不能把商户密钥放在小程序里。

很多人问的“uniapp里打包成App支付和微信小程序支付流程参数是否相同”：下单逻辑在后端可以高度复用，但客户端的调用方式不一样。uniapp里用uni.requestPayment做了一层统一封装，App端可能走的是原生支付SDK，小程序端还是调微信小程序的wx.requestPayment，回调地址也可能是不同的。所以后端接口要区分渠道字段，按platform返回适合当前端的参数。

“小程序可以加入支付宝支付渠道吗”这个问题也很常见：小程序环境里不能直接拉起支付宝App，更不可能并列展示微信支付和支付宝支付两个按钮让用户直接选。微信小程序内如果要接支付宝，只能做中间跳转，比如跳到支付宝H5收银台或者跳转到对方的支付宝小程序，但这类操作有审核风险，而且用户跳出体验很割裂，我的建议是能不接就不接，真需要双渠道可以考虑用公众号H5或独立App承载。

还有iOS虚拟支付限制：微信小程序里的虚拟商品支付（会员、课程、音视频、打赏）在iOS端是走不通的，苹果要求虚拟商品必须走IAP，而微信小程序虚拟支付对iOS并不开放。所以你做知识付费这类的虚拟商品，iOS端要隐藏支付入口或提示“请用安卓设备购买”，你拦截不了也不能绕过。这个限制是平台规则硬性的，别指望用外链或者web-view能绕过去。

5. 常见问题排查与调试实录

5.1 高频报错速查表

平时在群里看到的问题，有相当一批是重复的。我整理了一个高频报错速查表，对照排查能省不少时间：

这个表只是抛砖引玉，实际项目里你会碰到更多千奇百怪的报错。我自己的习惯是：遇到报错先看errMsg字段，它已经把问题说得七七八八了，然后去微信官方文档查对应的errCode，不要一上来就改代码。

5.2 iOS网络请求失败率高排查思路

热词里有“ios机型出现网络请求失败的率很高。web分析6001”，这个问题我实际排查过。当后台统计显示iOS真机网络请求失败率明显高于安卓时，常见的原因有几个。第一是TLS版本和证书链，iOS对TLS 1.2以上版本要求比较严格，如果服务器只支持旧的TLS1.0或1.1，或者证书链不完整、中间证书没配好，iPhone上就会握手失败，而安卓端可能因为兼容性比较好还能跑通。第二是ATS（App Transport Security），小程序在iOS上对HTTP明文请求是直接禁用的，如果你的请求还是http，iOS端必挂，安卓可能还能发，这跟“不校验合法域名”不是一回事。第三是HTTP/2连接复用问题，在弱网切换WiFi和蜂窝网络的时候，NSURLSession的连接池可能没有及时重建，导致请求一直等旧连接。

排查的时候，我建议按这个顺序：先用真机开vConsole看具体fail信息和耗时，区分是握手失败还是超时；让后端看access log里有没有请求到达、TLS版本号是多少、握手耗时是多少；如果怀疑是证书问题，用在线工具检测一下域名证书链完整性；最后再检查客户端请求头的Host和IP是否正常。像6001这类错误码，在不同平台可能有不同定义，网上信息比较杂，别只盯着错误码本身，结合前后端的日志定位才是关键。

5.3 调试与抓包：自己小程序的流量怎么看

做小程序开发，难免要抓包看数据。很多人一上来就装Fiddler、Burp这类工具，其实微信开发者工具自带的Network面板在90%的场景下都够用，特别是调试API请求时能够直接看到请求头、响应数据、耗时。真机调试时也可以打开vConsole，在Console和System面板里看到部分网络信息。

如果你确实需要抓真机的完整HTTPS内容，一般做法是让手机流量走PC上的调试工具，并在手机上安装对应的根证书。这里要特别强调：这类操作只能用于调试自己的小程序、自己的服务器，不要拿去抓别人家的接口，更不要尝试获取他人敏感信息，这是基本的合规底线。而且这种调试方式在证书校验严格的小程序版本里不一定能生效，微信本身也有反调试机制，不要想着去钻空子。我的经验是：优先用开发者工具的Network面板和vConsole，配合后端日志，能解决绝大多数问题；真机抓包属于最后的手段，没必要一上来就上重武器。

5.4 多端框架该怎么选：原生、uniapp、Taro

热词里有一句“uniapp 开发 微信小程序 vs android/ios/鸿蒙”，这其实是个特别容易引发争论的话题。从API角度看，我的态度是这样的：如果你只做微信小程序一个平台，那就用原生，原生API支持最全、能第一时间用微信最新的能力，调试也最直接，不存在框架适配可能带来的隐藏问题。如果你明确要做多端，那就认真评估uniapp或Taro这类跨端框架。

uniapp把微信小程序API封装成了uni.的统一接口，比如uni.request对应wx.request、uni.getLocation对应wx.getLocation，做一套代码跑微信、H5、App确实爽。但封装也意味着滞后，当微信新增一个API时，uniapp往往要过一段时间才跟进；一些深度能力，比如蓝牙BLE、地图自定义图层、WebView桥接、自定义导航栏的精细控制，在跨端框架里需要用条件编译自己去调wx.。所以我的建议是：跨端框架可以选，但底层的兼容层一定要自己留好，遇到奇怪问题先怀疑框架封装，再怀疑自己代码。鸿蒙这块目前更特殊，不同平台的API差异不只在名字上，还在能力和权限模型上，想做全平台交付，就要做好每条业务线单独适配的心理准备。

回到我自己的体会，这一路做下来最大的感受是：不要急着封装一切，先把API本身的行为和边界搞清楚。很多人一上来就封装wx.request，结果连res.data和res.statusCode的区别都没弄明白，遇到报错就抓瞎。API是拿来用的，也是拿来调试的，读报错、看文档、查errCode，这三件事做好，你已经超过了大多数新手。下一篇我打算把小程序里的登录态设计和请求重放机制单独拆开来讲，因为这块绕来绕去的坑实在太多，值得用一整篇的篇幅慢慢盘。