做支付宝小程序开发的同学，大概率都遇到过my.api调用失败的情况，比如想拿用户信息、选照片或者提交表单，接口就是不生效，报错信息还看不懂，折腾半天找不到问题。今天就把常见的坑都扒出来，再讲怎么用正确的异步写法把这些坑绕过去，不管你是刚入门的新手，还是想优化老项目的开发者，都能看懂用得上。
一、支付宝小程序my.api调用失败的常见原因排查
1.1 基础权限配置没做对
你想调用某些敏感接口，比如获取用户手机号、地址这些，支付宝小程序必须先在项目的app.json里声明权限，不然就算代码写对了，调用也会直接失败。举个例子，调用my.getPhoneNumber接口获取用户手机号，要是没在app.json里配权限的话，连调用的机会都没有。正确的配置应该是在app.json的permission节点加上对应权限，要是没加，调用就会直接报权限相关的错误，不会走到fail回调就终止了。
1.2 接口参数不符合要求
每个my.api接口都有自己的参数规则，不是随便传值就行。比如调用my.chooseImage选照片，参数里的count是最多选多少张，支付宝小程序里这个参数最大只能是9，要是你传了10，接口直接报错“参数无效”。还有比如调用my.request请求后端接口，要是你传的data格式不对，比如把对象写成字符串，后端解析不了，接口也会失败。举个简单的例子，你原本写的count:10，实际换成count:9就符合要求了。
1.3 网络环境问题
支付宝小程序对网络要求挺严格的，比如真机调试的时候，你用的是电脑本地的http地址，比如http://127.0.0.1:8080，真机上是没法调用的，必须是合法的https地址，而且域名还要在支付宝小程序的后台配置合法域名列表里。还有就是要是用户的手机网络不好，比如信号差、断网，接口调用也会失败，这个时候就需要做网络异常的降级处理。
1.4 小程序基础库版本不兼容
有些新的my.api接口是在新版本的基础库才支持的，要是你用的小程序基础库版本太老，调用新接口就会失败。比如支付宝小程序官方刚出的某个新接口，你用的基础库是2.0版本，而这个接口需要2.5版本以上，那调用就会报错，提示接口不存在。这个时候只要把基础库版本升级到最新的稳定版就可以解决。
二、异步处理的最佳实践
原来的my.api接口是用回调函数的，比如写的时候是my.api({success: ()=>{}, fail: ()=>{}})，要是多个接口串行调用，比如先获取用户ID，再根据用户ID获取订单，再根据订单ID获取详情，这样一层层嵌套，就会变成“回调地狱”，代码乱得看不懂，维护起来特别麻烦。所以最好的办法是把这些异步接口封装成Promise，用async/await的写法，代码更清晰，调试也方便。
2.1 用Promise封装my.api接口
举个例子，我们封装一个通用的调用方法，把所有my.api都转换成Promise形式，这样就能用await来等待结果，避免回调嵌套。代码示例：
// 技术栈：支付宝小程序原生JS
function myApiPromise(apiName, params = {}) {
return new Promise((resolve, reject) => {
my[apiName]({
...params, // 把传入的参数展开
success: (res) => resolve(res), // 成功就把结果返回给Promise
fail: (err) => reject(err) // 失败就把错误返回给Promise
})
})
}
这个封装的意思就是，不管你要调用哪个my.api接口，只要传接口名和参数，就能得到一个Promise对象，后面用await来等待它的结果，比原来的回调写法清爽多了。
2.2 异步结果的统一处理
封装成Promise后，就可以用try/catch来捕获错误，统一处理，不用每个接口都写success和fail。比如调用选照片的接口：
// 技术栈：支付宝小程序原生JS
async function chooseImages() {
try {
// 调用选照片接口，count设为最多9张，符合支付宝的参数要求
const res = await myApiPromise('chooseImage', { count: 9 })
console.log('选照片成功，照片路径：', res.apFilePaths)
return res.apFilePaths
} catch (err) {
// 统一处理选照片失败的情况，给用户弹友好提示，不要报错码
my.showToast({ content: '选择照片失败，请重试' })
console.error('选照片失败：', err)
return null
}
}
这里把选照片的逻辑都包在try/catch里，只要接口失败，就会进到catch里，统一处理错误，用户体验也更好，不用每个地方都重复写错误提示。
2.3 异步流程的错误兜底
不管接口封装得再好，都可能出现意外情况，比如用户突然断网，这个时候就需要做兜底处理。比如在catch里除了弹提示，还可以做降级处理，比如用本地存储的旧数据，或者给用户一个重试的按钮，让用户可以重新操作，避免流程卡住。比如刚才的选照片接口，要是失败了，除了弹提示，还可以加个重试的逻辑，或者让用户从相册选单张照片，不要强制要求选9张，给用户灵活选择的空间。
三、实际应用场景分析
3.1 表单提交场景的异步处理
比如用户要提交一个订单，这个过程需要先获取用户的openid（支付宝用户唯一标识），然后把openid和订单数据一起提交到后端。原来的回调写法会嵌套很多层，现在用async/await就很清晰，代码从上到下读，容易理解：
// 技术栈：支付宝小程序原生JS
async function submitOrder(orderData) {
try {
// 第一步：获取用户openid
const authRes = await myApiPromise('getAuthUserInfo')
const openid = authRes.authUserInfo.openId
// 第二步：提交订单给后端，把openid和订单数据一起传
const orderRes = await myApiPromise('request', {
url: 'https://yourserver.com/api/submitOrder',
method: 'POST',
data: { openid, ...orderData }
})
my.showToast({ content: '订单提交成功' })
return orderRes
} catch (err) {
my.showToast({ content: '订单提交失败，请检查网络' })
return null
}
}
这里两个接口是串行的，先拿openid再提交订单，逻辑很清楚，不会像回调那样绕来绕去。
3.2 多接口并行场景
比如页面要同时显示两个内容：用户的订单列表和地址列表，这两个接口没有依赖关系，可以并行调用，节省时间，让页面加载更快。原来的回调写法要嵌套，现在用Promise.all就可以轻松实现：
// 技术栈：支付宝小程序原生JS
async function loadPageData() {
try {
// 两个接口并行调用，一起发请求，节省时间
const [orderRes, addressRes] = await Promise.all([
myApiPromise('request', { url: '/api/getOrders' }),
myApiPromise('request', { url: '/api/getAddress' })
])
// 处理两个接口的结果，直接取对应的数据
console.log('订单列表：', orderRes.data)
console.log('地址列表：', addressRes.data)
return { orders: orderRes.data, addresses: addressRes.data }
} catch (err) {
my.showToast({ content: '页面数据加载失败' })
return null
}
}
这样两个接口一起发请求，页面加载速度会快很多，适合这种不依赖的接口场景，提升用户体验。
四、注意事项
开发支付宝小程序的时候，有几个细节要注意：第一，接口权限一定要先配置，不要等代码跑起来才发现没配，在开发前先查下支付宝小程序的权限文档，需要的权限都在app.json里加好。第二，参数要严格按文档传，比如必填的参数有没有漏，类型对不对，比如数字就不要传字符串，不然接口会报错。第三，网络问题是真机调试最常遇到的，一定要用合法的https地址，并且域名在后台配置过，不然真机上调用失败。第四，基础库版本要注意，尽量用最新的稳定版，避免旧版本不支持新接口。第五，异步处理的时候，不要遗漏错误处理，每个异步操作都要有兜底，不要让用户看到空白或者错误页。
五、总结
支付宝小程序my.api调用失败的原因其实不难排查，主要就是权限、参数、网络、版本这几个点，只要按顺序查就能找到问题。而异步处理的最佳实践就是把回调转换成Promise，用async/await来写，代码更清晰，维护也方便，不管是串行还是并行的接口，都能轻松处理。平时开发的时候多注意刚才说的几个细节，就能避开大部分常见的坑，写出稳定的小程序，给用户更好的体验。
评论
围绕“支付宝小程序中my.api调用失败的原因排查与异步处理最佳实践”参与讨论