去年底接了个活儿，帮朋友的小店做个微信小程序，功能很简单，就是商品展示加在线预约。我以为这玩意儿不难，毕竟小程序开发 API 文档摆在那儿，密密麻麻的接口说明看着挺唬人。结果真动手后才发现，踩坑的体验比读文档深刻得多。比如 wx.request，你以为照搬文档就能搞定数据请求，结果跨域、参数格式、返回数据解析每一步都得亲手试错。最离谱的是，有个 API 的返回值在 Android 和 iOS 上格式不一样，愣是让我排查了半天。这事让我意识到，API 不是拿来就能用的魔法棒，它更像一个需要反复磨合的工具，用对了能省时间，用错了能让你怀疑人生。

先说说最常用的 API，比如 wx.login 和 wx.getUserInfo。这俩接口是用户授权的核心，但很多人一上来就掉进坑里。wx.login 拿到的临时 code 必须传给后端去换 session_key，可这 code 有效期才五分钟，要是后端处理慢了或网络卡顿，用户就得重新授权。我见过一个案例，某电商小程序因为没处理好时序，导致用户下单时 session 过期，订单直接丢了一半。另一个常见问题是 wx.getUserInfo，官方现在改成必须由用户主动点击按钮才能触发授权，很多新手直接在页面加载时弹授权框，结果用户一拒绝，后续功能全崩。正确的做法是先判断用户是否已授权，未授权时引导用户手动点击按钮，而不是硬来。这些细节文档里都有，但没踩过坑的人根本记不住。

再说说数据缓存，wx.setStorage 和 wx.getStorage 看着简单，实际坑也不少。比如存储容量限制，单个 key 不能超过 1 MB，整个缓存不能超过 10 MB。有次我帮一个资讯类小程序做优化，发现它把文章全文存进缓存，一篇长文就几百 KB，用户多看几篇就爆了。后来改成只存标题和摘要，正文用本地临时文件，才解决问题。还有个容易忽略的点，wx.getStorage 是同步操作，如果在大循环里频繁调用，页面会卡得像 PPT。我见过有人写了购物车功能，每次加减商品都读一次缓存，结果用户在低端手机上点一下要等两秒。正确做法是把数据先存到内存变量里，只在需要持久化时再写缓存。

文件上传和下载这块，wx.uploadFile 和 wx.downloadFile 是高频踩雷区。上传时，很多人以为直接传文件路径就行，实际上需要先通过 wx.chooseImage 或 wx.chooseVideo 获取临时路径，而且这个路径只在当前生命周期有效。一次我帮摄影社区做小程序，用户上传照片后，后台返回了云存储地址，前端却把这个地址直接存进数据库。下次用户再打开，图片路径已经失效。正确的做法是上传成功后把云端返回的永久地址保存下来。下载方面更坑，wx.downloadFile 返回的是临时文件路径，系统会自动清理，想长期保存必须调用 wx.saveFile。我见过有人下载用户头像后直接展示临时路径，几天后头像全变成空白。

实时通信 API，尤其是 WebSocket，很多人觉得简单，但坑在心跳机制和重连逻辑。微信小程序的 WebSocket 连接，如果 30 秒内没有数据交互，会被自动断开。我帮一个在线客服小程序做优化时，发现用户发完消息后，如果客服没及时回复，连接就断了，等客服再回消息时用户根本收不到。解决方案是每隔 20 秒发送一次心跳包，同时监听 onClose 事件，一旦断开就自动重连。还有一点，connectSocket 的 url 参数必须使用 wss 协议，不能用 ws，否则在正式环境会直接报错。这些坑文档里都有，但很多人只关注功能实现，忽略了边界情况。

地图和位置 API，wx.getLocation 和 wx.chooseLocation，这对接口在隐私合规上是个大雷。微信官方要求，小程序使用位置信息必须经过用户授权，而且授权弹窗的文案必须清晰说明用途。我见过一个天气小程序，用户在首页弹了授权框，点“拒绝”后，后续所有功能都瘫痪。正确的做法是只在真正需要位置的页面才触发授权，比如“附近门店”页，而不是一进来就弹。还有个性能问题，wx.getLocation 在低端手机上执行很慢，有时要等好几秒，用户快速点击可能导致多次请求。建议在调用前先判断缓存中是否有效位置数据，避免重复请求。

支付 API，wx.requestPayment，是最敏感也最容易出错的接口。很多人以为调通这个接口就完事了，实际坑在参数签名和订单状态同步。微信支付的签名算法要求严格，参数顺序、大小写、编码方式都必须精准，稍有差错就会报错。我帮一个餐饮小程序做支付时，发现用户支付成功后后端没收到回调，订单一直显示“未支付”。排查后发现是回调 URL 配置错误，微信服务器连不上。还有一点容易被忽略，wx.requestPayment 的 success 回调并不代表支付成功，只说明前端调起支付成功，真正的支付结果必须由后端查询微信服务器。很多新手直接在前端判断 success 就更新订单状态，导致支付失败也显示“支付成功”。

云开发 API，像 callFunction 和 database，是微信官方推的解决方案，但坑也不少。云函数冷启动最让人头疼，第一次调用可能要等几秒，用户会误以为小程序卡死。我见过一个工具类小程序，把所有逻辑都放在云函数里，每次操作都要等几秒，用户流失率暴增。解决方案是把常用数据缓存到本地，减少云函数调用频率，或者使用云数据库的实时监听功能，避免频繁请求。还有个坑是云数据库的权限设置很严格，默认只允许创建者读写，如果不手动配置，用户连自己的数据都查不到。很多人开发时用管理员权限测试没问题，一上线就报错。

说说那些冷门但实用的 API，比如 wx.createAnimation 和 wx.pageScrollTo。前者做动效很好用，但很多人不知道怎么控制时序。想做渐入动画，直接调用会瞬间完成，必须配合 setTimeout 或 Promise。后者用于页面滚动，但如果页面内容还没渲染完就调用，会滚到错误位置。我帮一个长列表页面做优化时，用了 pageScrollTo 想回到顶部，却因为列表数据是异步加载，用户点按钮时页面高度还没更新，结果滚到了中间。解决方案是等数据渲染完成后的 nextTick 再调用滚动 API。这些细节文档里只是一笔带过，但实际开发中能让你省下三天工时。

说到底，微信小程序的 API 就像一把双刃剑。用得好，能快速搭建功能完善的应用；用不好，每个接口都可能变成坑。关键不在于背下所有参数，而在于理解每个 API 的边界条件和异常场景。我见过太多开发者，文档读了三遍，代码写了两天，结果上线第一天就崩了。原因很简单，他们只关注“怎么用”，没想过“用不好会怎样”。这行当里，真正的经验不是 API 列表，而是那些踩过的坑、填过的雷。所以下次再看 API 文档时，别急着往上写代码，先想想：这个接口在什么情况下会出错？用户操作失误会怎样？网络断了怎么办？把这些想明白了，你才算真正掌握了它。