小程序开发者工具如何使用支付宝沙箱模拟支付并开启 API 代理

2026-10-24支付阿杰

结论

可以用支付宝沙箱验证小程序支付流程，但要满足两个条件：

项目需要运行在支付宝小程序开发者工具或支付宝真机环境中，不能通过微信开发者工具调用支付宝支付。
支付订单需要由服务端创建。如果开发者工具提示”请开启 API 代理”，需要在工具中启用 API 代理，将支付接口请求转发到实际的后端服务。

API 代理只负责转发请求，无法代替支付宝沙箱配置、服务端签名和支付接口调用。部分版本的模拟器不能完整拉起收银台，遇到这种情况，需要改用真机预览继续测试。

支付调用流程

支付宝小程序支付通常按以下流程完成：

小程序
  ↓ 请求业务后端
业务后端
  ↓ 调用支付宝沙箱 alipay.trade.create
支付宝沙箱
  ↓ 返回 trade_no
业务后端
  ↓ 返回 trade_no
小程序
  ↓ 调用 my.tradePay
支付宝沙箱收银台

私钥、应用证书和签名逻辑必须保存在服务端，不能写进小程序代码。

配置支付宝沙箱

先在支付宝开放平台的沙箱环境中准备好以下配置：

沙箱应用的 app_id
应用私钥
支付宝公钥，或支付宝证书、公钥证书和根证书
沙箱网关地址
沙箱买家账号
异步通知地址 notify_url

服务端使用的 app_id、密钥和网关必须来自同一个沙箱应用，不能混入正式环境的配置。

沙箱网关通常配置为：

https://openapi-sandbox.dl.alipaydev.com/gateway.do

具体地址以支付宝开放平台当前沙箱控制台显示的配置为准。

开启 API 代理

支付宝小程序开发者工具的版本不同，入口名称也可能略有差异，通常可以在以下位置找到：

项目详情 / 项目设置
  → 本地设置或代理设置
  → API 代理
  → 开启

有些版本会把相关入口放在开发者工具顶部菜单的”设置""代理”或”调试设置”中。开启后，需要配置代理目标，例如：

代理路径：/api
目标地址：http://127.0.0.1:3000

配置完成后，小程序发出的请求：

/api/alipay/create-order

会被转发到：

http://127.0.0.1:3000/api/alipay/create-order

如果代理功能支持路径重写，也可以先删除 /api 再转发。是否需要重写，要看后端的真实路由。

修改代理配置后，建议重新编译项目。如果工具仍在使用旧配置，可以重启开发者工具。

小程序端示例

小程序先向业务后端申请创建订单：

my.request({
  url: '/api/alipay/create-order',
  method: 'POST',
  data: {
    orderId: 'ORDER_202609090001',
    amount: '0.01'
  },
  success(res) {
    const tradeNO = res.data && res.data.tradeNO;

    if (!tradeNO) {
      console.error('服务端未返回 tradeNO', res);
      return;
    }

    my.tradePay({
      tradeNO,
      success(result) {
        console.log('支付调用结果', result);
      },
      fail(error) {
        console.error('支付调用失败', error);
      }
    });
  },
  fail(error) {
    console.error('创建订单失败', error);
  }
});

tradeNO 必须是服务端调用 alipay.trade.create 后获得的支付宝交易号，不能由小程序自行生成。

服务端示例

下面只展示 Node.js 服务端的核心结构。支付宝 SDK 的版本以及采用公钥还是证书模式，都会影响初始化参数，具体写法以实际安装版本的接口定义为准。

import express from 'express';
import AlipaySdk from 'alipay-sdk';

const app = express();
app.use(express.json());

const alipaySdk = new AlipaySdk.default({
  appId: process.env.ALIPAY_APP_ID,
  privateKey: process.env.ALIPAY_APP_PRIVATE_KEY,
  alipayPublicKey: process.env.ALIPAY_PUBLIC_KEY,
  gateway: 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'
});

app.post('/api/alipay/create-order', async (req, res) => {
  const { orderId, amount } = req.body;

  if (!orderId || !/^\d+(\.\d{1,2})?$/.test(amount)) {
    return res.status(400).json({
      message: '订单号或金额不合法'
    });
  }

  try {
    const result = await alipaySdk.exec('alipay.trade.create', {
      bizContent: {
        out_trade_no: orderId,
        total_amount: amount,
        subject: '小程序沙箱测试订单',
        buyer_id: process.env.ALIPAY_SANDBOX_BUYER_ID
      }
    });

    res.json({
      tradeNO: result.tradeNo || result.trade_no
    });
  } catch (error) {
    console.error('创建支付宝订单失败', error);
    res.status(500).json({
      message: '创建支付订单失败'
    });
  }
});

app.listen(3000, () => {
  console.log('Server listening on http://127.0.0.1:3000');
});

SDK 版本不同，返回字段的名称也可能不同。需要打印实际响应，确认使用的是 tradeNo 还是 trade_no，不要直接假定字段名称。

如果代理仍然不通

可以依次检查：

本地后端是否已经启动，端口是否与代理目标一致。
小程序的请求路径是否命中代理规则。
代理目标使用 127.0.0.1 时，服务是否确实运行在开发者工具所在的电脑上。
使用真机预览时，手机无法直接访问电脑的 127.0.0.1，需要改用局域网地址或可以访问的 HTTPS 测试域名。
后端接口域名是否已加入支付宝小程序的服务器域名配置。
HTTPS 证书是否有效。正式环境不要依赖”忽略域名校验”之类的调试选项。
沙箱应用、网关、密钥和买家账号是否都来自沙箱环境。
my.tradePay 接收的是支付宝交易号，还是商户自己的 out_trade_no。
当前应用是否具备对应的支付能力，测试账号是否属于正确的沙箱应用环境。

模拟器无法拉起支付时怎么办

开启 API 代理后，如果创建订单接口已经调用成功，但模拟器仍然无法显示收银台，问题不一定出在代理配置上。支付涉及账号登录、客户端能力和收银台跳转，部分版本的开发者工具只能调试到创建订单或调用支付 API 这一步。

遇到这种情况，需要通过支付宝客户端进行真机预览，并登录沙箱买家账号完成测试。支付完成后，服务端还需要主动查询订单状态或验证异步通知，不能只根据小程序端的成功回调把订单标记为已支付。