非程序员的AI造物日记微信虚拟支付踩坑实录

��每个坑都按"症状 → 原因 → 怎么避"三段结构来写。建议直接对号入座，哪里卡住了就看哪段。

现象

点击支付按钮后，既没有弹出支付界面，也没有任何报错提示，就这么安静地失败了。

为什么会这样

微信有一个叫 mode 的参数，官方文档标注为"可选"，但实际上如果你不填，支付请求会直接被拒掉，而且错误信息非常隐蔽（errno 1001），不懂的人根本不知道是哪里出了问题。

怎么避

告诉你的开发AI或程序员：wx.requestVirtualPayment 调用时，mode 参数必须填写，虚拟商品场景填 short_series_goods。文档说"可选"，实际是"必填"。

⚠️ 记住这个规律：微信文档里标"可选"的字段，不代表不填没事。遇到奇怪的失败，先检查是不是漏了什么参数。

现象

支付请求发出去了，但微信返回签名验证失败。所有参数看起来都对，就是不通过。

为什么会这样

微信虚拟支付有个隐藏规则：签名里的字段，必须严格按照字母顺序排列，而且这个排序必须在服务器端完成，不能在手机小程序端修改。如果顺序不对，签名就会静默失败——没有明显报错，只告诉你"签名错误"，完全不说哪里错了。

怎么避

让后端程序员注意：signData 对象里的字段，必须按字母顺序（A→Z）排列后再做签名。同时，前端收到签名后必须原样透传，不能重新整理字段顺序。这个坑最麻烦的地方是报错信息没有任何帮助，只能靠逐字段核对来排查。

��字段顺序错误不会有明显提示，只会静默签名失败，排查成本极高。建议接入前先让程序员把这条单独验证一次。

现象

用户在微信里完成了付款，但返回小程序后，页面显示"支付失败，请联系客服"。用户钱扣了，功能没开通，双方都很崩溃。

为什么会这样

这是今天最隐蔽的一个坑。很多人（包括我）的第一版代码逻辑是：支付弹窗成功弹出后，立刻去服务器查这笔订单有没有完成。但这个逻辑是错的。支付弹窗"成功弹出"，不等于用户已经付完钱。用户这时候还在微信的付款页面里，根本还没点确认。这个时候去查订单，当然查出来是"未支付"。

怎么避

正确的流程是：支付弹窗弹出→ 用户完成付款 → 用户点击"返回商家"回到小程序 → 这时候页面会触发"onShow"事件 → 在 onShow 里才去查订单。  简单说：查单的时机不是支付弹窗弹出，而是用户从微信支付页面返回小程序的那一刻。

��支付弹窗成功≠ 用户已付款。让你的程序员把查单逻辑放在 onShow 里，而不是放在支付回调的 success 里。

现象

解决了查单时机的问题后，测试时还是不对。用沙箱环境付款，订单状态永远是"未支付"，死活变不成"已支付"。

为什么会这样

微信的正式环境，用户付完款后，微信会主动通知你的服务器"这笔订单已支付"，服务器收到通知才会把订单改成已支付状态。  但沙箱（测试）环境下，微信根本不发这个通知。所以订单永远停在未支付，不管你操作多少次都一样。

怎么避

沙箱测试时，让程序员临时绕过查单逻辑，直接信任"支付弹窗成功"这个信号。同时必须在代码里加注释标记这是沙箱专用逻辑，上线前必须恢复正式查单流程。  重要提醒：这个临时方案如果不在上线前改回来，会有严重安全漏洞——任何人不付款也能开通功能。

⚠️ 沙箱不发支付回调 = 测试环境必然失败。临时方案必须加注释标记，上线前必须还原，这是硬性要求。

现象

PDF下载功能在电脑模拟器里完全正常，换到手机上测试，点击下载没有任何反应，成功和失败的回调都不触发，就像什么都没发生一样。

为什么会这样

微信小程序有一个"合法域名"白名单，只有在白名单里的域名，小程序才能访问。在电脑上调试时，可以勾选"不校验合法域名"来跳过这个检查，但这个设置只对电脑模拟器有效，真机上该验证还是验证。  更容易踩的坑在于：发起请求（request）和下载文件（downloadFile）是两个完全独立的白名单，需要分别配置。很多人只配置了请求域名，忘了同时配置下载域名，导致真机下载失败。

怎么避

去小程序管理后台，确认你的服务器域名同时出现在三个白名单里：request合法域名、downloadFile合法域名、uploadFile合法域名。缺任何一个，对应功能在真机上就会失效。  真机调试的通用方法：如果看不到报错，可以让程序员在代码里加临时弹窗，把接口返回内容直接显示在手机屏幕上，比对着电脑看日志要直接得多。

��电脑模拟器正常≠ 真机正常。三个域名白名单（request / downloadFile / uploadFile）必须分别在后台配置，缺一不可。

现象

PDF下载接口，服务器自测完全正常，但真机访问就是403（权限拒绝）。

为什么会这样

最后发现是Token（访问密钥）里两个字符的大小写顺序写反了。这种错误肉眼极难发现——字符都对，字符数也对，就是顺序不一样。因为Token通常在多个地方使用（服务器配置、前端代码），手敲的时候很容易出现这种偏差。

怎么避

Token、密钥这类字符串，不要在不同地方分别手敲。统一维护在一个配置文件或环境变量里，所有地方引用同一个来源。遇到403，第一反应应该是比对Token，而不是检查业务逻辑。

⚠️ Token大小写错误，肉眼很难发现。遇到403，先对比Token，再查别的。

现象

文件能正常下载和预览，但右上角没有任何菜单，用户没法保存，也没法转发，只能干看着。

为什么会这样

微信提供的文件预览功能，默认不显示分享/保存菜单，需要明确开启。这属于文档里有但很容易忽略的配置项。

怎么避

让程序员在打开文件时加上 showMenu: true 参数，就能显示右上角的菜单。同时，下载时指定文件名可以避免文件名显示乱码。  另外需要告知用户：iOS用户通过这个菜单无法直接"保存到手机相册"，只能转发给朋友或用其他App打开。建议提前在界面里说明，避免用户投诉。

��showMenu: true 这一行不加，用户就只能看不能存。iOS保存到手机的方式与安卓不同，建议在UI里加说明。

#

检查项

说明

1

mode 参数已填写

虚拟商品场景必须填 short_series_goods，文档说可选，实际必填

2

签名字段按字母序

服务端签名时字段必须按A→Z排列，前端禁止重排

3

查单时机在 onShow

支付弹窗弹出≠ 支付完成，查单必须放在用户返回小程序之后

4

沙箱逻辑已还原

测试用的临时跳过逻辑，上线前必须恢复正式查单流程

5

Token统一管理

不要多处手敲，维护在配置文件中，避免大小写错误

6

showMenu已开启

openDocument 调用时加 showMenu: true，否则用户无法保存或分享

7

下载时指定文件名

不指定则显示系统随机乱码文件名，体验差

8

三个域名白名单均已配置

request / downloadFile / uploadFile 三个白名单需分别在小程序后台配置