1. 先说清楚：微信运动步数到底是怎么被小程序拿到的

很多人第一次做步数相关的小程序，脑子里想的是"调个接口就能拿到数字"，结果真机一跑，授权弹窗都没弹出来，或者弹了点了允许，返回的却是空数组。我前后在三个不同的小程序项目里踩过这个坑，最难受的一次是测试机上跑得好好的，换到另一台机型直接授权失败，日志里只有一句含糊的错误码，连个方向都不给。

所以这篇东西不是教科书，是我把这条链路从头到尾捋了一遍之后的复盘。核心关键词是微信运动步数、真机授权失败、数据解密这三件事，读完之后你应该能做到：知道步数数据从哪来、为什么开发者工具里看着正常真机却不行、加密数据怎么解、以及哪些坑是文档里不会写但一定会遇到的。适合已经能写小程序页面、但对开放能力授权链路不熟的同学，也适合被"授权失败"卡了半天找不到原因的人。

先建立一个整体认知，不然后面条目会散。微信运动步数在小程序侧拿到手，走的是一条两段式的路：第一段是你调用接口，唤起用户授权，用户同意之后你拿到一串加密的、带时间窗口的数据；第二段是这串数据你自己解不开，必须把它连同会话凭证一起发给自己的服务端，由服务端用会话密钥去解密，才能得到明文的步数数组。注意这里有个关键点：小程序端从头到尾拿不到明文步数，它只是个搬运工，真正的解密动作发生在服务端。

这个设计直接决定了后面所有坑的形态。真机授权失败，多半是卡在第一段；解密报错，几乎全在第二段。而开发者工具之所以"看起来正常"，是因为它的模拟环境和真机在会话状态、用户身份、授权持久化上都有差异。把这条链路想明白，遇到问题你就知道该往哪一段去找，而不是盲目改代码。

再说一句大实话：这套能力对用户隐私的要求是比较高的，接口本身对调用频率、数据时间范围都有约束，数据还带有效期，过期就作废。这既是限制也是保护，理解这一点，你就不会问"为什么不能一次拿到一整年的步数"这种问题了。

2. 授权链路的第一道坎：为什么真机上授权弹窗不出现

2.1 授权失败的四种典型表现与对应根因

描述"授权失败"其实太笼统了，我在排查时习惯先把它拆成具体症状，因为不同症状指向完全不同的原因。下面这张表是我自己整理的对照表，遇到问题先对号入座，能省掉一大半瞎猜的时间。

表格第一行那个"毫无反应"是最迷惑人的。我遇到过一次，代码逻辑翻来覆去看了两小时，最后发现是后台根本没给这个小程序开通相应的数据能力，接口调用直接被静默拦掉。这种问题不会给你任何有意义的报错，只能靠去后台核对。

第二行的"返回空数组"也很有意思。它不是失败，接口是成功返回的，只是数组里没元素。原因通常有两个：一是这台测试机当天确实没走过路（模拟器或闲置设备很常见），二是你传的时间范围参数超出了允许的窗口。很多人看到空数组就以为解密出问题，实际压根还没走到解密那一步。

2.2 授权状态是"记住"的，这点必须提前设计

这是最容易忽略的一条：用户的拒绝会被记住。一旦用户点了拒绝，后续再调用接口往往不会重新弹窗，而是直接给你一个失败结果。很多同学在调试时反复点拒绝想看不同分支，结果把自己的测试账号搞成了"永久拒绝"状态，然后再也调不出来，误以为是代码坏了。

正确的做法是在设计阶段就把这个状态考虑进去。我的习惯是：调用前先做一个能力检测，拿到当前授权状态，如果处于"已拒绝"，就不硬调接口，而是展示一个引导，让用户自己去设置页打开。硬调只会不断失败，体验极差。

// 调用前先查状态，避免无效调用 wx.getSetting({ success(res) { const auth = res.authSetting['scope.werun']; if (auth === false) { // 已拒绝，引导用户去设置页手动开启 showGuideToSetting(); return; } // undefined 表示从未询问过，true 表示已授权，都可以直接调用 requestWeRunData(); } });

这段代码的价值不在于技术难度，而在于顺序。先查后调，而不是先调再看结果，能避免大量无意义的失败调用，也能让你在日志里一眼看出问题出在"用户拒绝"还是"接口异常"。

2.3 基础库版本与真机系统差异的隐性影响

还有一个坑藏得很深：基础库版本。开发者工具默认跑的是较新的基础库，而真机上用户的实际版本可能落后不少。某些能力在低版本基础库里表现完全不同——可能不支持、可能静默失败、可能返回结构不一致。

我一般的处理是在入口处做一次版本判断，低于某个门槛就提示升级，而不是让它带着不确定性往下跑。判断方式很简单，取到当前基础库版本号做比较即可。这个动作只要几行代码，但能挡掉一批"只在某台老设备上复现"的诡异问题。

另外真机的系统差异也要留意。不同系统对后台数据、健康数据的开放程度不一样，某些机型上用户即便授权了，实际数据也可能因为系统层面的限制而为空。这种时候不要怀疑自己的代码，先用一台确定有数据的设备作为基准，把变量控制住。

提示：排查授权问题时，永远先用一台"确定有真实运动数据、系统较新、基础库较新"的设备做基准测试。基准不通，别碰其他机型；基准通了，再逐个换设备对比，这样能把变量一个个排除掉。

3. 会话凭证没准备好，后面全是白费

3.1 登录流程与授权流程的先后顺序陷阱

这一节讲的是我见过最多人栽跟头的地方：授权之前必须先完成登录，拿到会话凭证。

听起来是常识，但实际写代码时非常容易搞反。因为授权那一步在小程序端看起来是"自包含"的——我调接口、用户点允许、我拿到加密数据，一气呵成。于是很多人就真的只写了这一段，然后把加密数据发给服务端，服务端说"我没有对应的密钥，解不了"。

原因在于：解密所需的会话密钥是登录环节产生的，它和服务端保存的会话状态是一一对应的。如果你在授权之前没走登录，或者登录了但服务端没把会话存好，那么这串加密数据到了服务端就是一堆无主的天书。

正确的顺序应该是：先登录换凭证，再把凭证安全地存到服务端并关联到当前用户，然后才发起授权拿加密数据，最后带着凭证去请求解密。这个链条任何一环断了，后面的解密必然失败，而且报错往往很含糊，让你以为是解密算法写错了。

// 正确顺序：登录 → 上报凭证 → 授权取密文 → 请求解密 function bootstrap() { wx.login({ success(loginRes) { // 把 code 发给自己的服务端，换回会话标识并落库 exchangeCodeForSession(loginRes.code).then(() => { // 会话就绪后，再发起授权 requestWeRunData(); }); } }); }

3.2 会话过期的真实影响：不是报错，是静默失败

会话是有有效期的。这一点大家都知道，但很多人低估了它的影响：会话过期之后，很多接口不会明确告诉你过期了，而是给你一个看起来"正常"但内容为空的结果。等你拿着这个空结果去解密，服务端那边要么解出空数组，要么直接抛异常。

我的处理习惯是在关键路径上加一层"会话有效性检查"：在发起授权和解密请求之前，确认当前会话是否还能用，不能用就先静默重登一次。这个动作对用户是无感的，但能挡掉大量"放着不动一段时间再回来就失败"的诡异问题。

还有一个细节：会话和用户是一一绑定的。如果你的服务端把会话存在一个全局变量里，多个用户并发时就会互相覆盖，表现是"A 用户拿到了 B 用户的步数"或者"解密时密钥对不上"。这种问题在单人测试时完全看不出来，一上量就炸。所以会话必须以用户维度存储，别图省事。

3.3 凭证传输必须走服务端，前端不该碰密钥

这条是安全底线，虽然不属于"踩坑"，但属于必须强调的规范：会话密钥只能存在于服务端，绝不能下发到小程序端。

我见过有人为了"省一次请求"，把密钥返回给前端，让前端自己解密。这个做法的问题不只是不安全，还会让整个链路变得极其脆弱——密钥一旦泄露，所有用户的数据都不设防。而且前端解密需要引入额外的加密库，包体积上去了，兼容性也差了，得不偿失。

正确的分工是：小程序端只负责拿密文、传密文；服务端负责持有密钥、执行解密、返回明文。职责清晰，出问题也好定位——解密失败就一定是服务端或会话的问题，前端不用背锅。

4. 加密数据解密：算法不难，难在细节对齐

4.1 解密三要素：密文、密钥、初始向量

走到这一步，说明授权已经通了，密文也拿到了。接下来是解密。先把三要素摆清楚：

• 密文：小程序端拿到的加密数据字符串
• 会话密钥：登录环节产生、保存在服务端的密钥
• 初始向量：随密文一起返回的另一个字符串

这三样缺一不可。解密算法本身是对称加密，业界通用，各家语言都有现成实现，所以"算法写错"其实很少见。真正出问题的地方在细节对齐：编码方式对不对、补位处理对不对、密钥和向量有没有被截断或转义。

我踩过最典型的一次：把初始向量直接当普通字符串传进了解密函数，没有做编码转换，结果解出来是乱码。排查了半天以为是密钥错了，实际是编码没对齐。这类问题的共性是——不报错，但结果是错的，比直接抛异常更难查。

4.2 一段可复用的服务端解密骨架

下面这段是 Node.js 环境下的解密骨架，逻辑在其他语言里也是一一对应的。注意每个参数的类型和编码，这是关键。

const crypto = require('crypto'); /** * @param {string} encryptedData 小程序返回的加密数据 * @param {string} iv 小程序返回的初始向量 * @param {string} sessionKey 服务端保存的会话密钥 */ function decryptWeRunData(encryptedData, iv, sessionKey) { // 三要素都必须是 Base64 字符串，这里统一解码成 Buffer const key = Buffer.from(sessionKey, 'base64'); const ivBuf = Buffer.from(iv, 'base64'); const dataBuf = Buffer.from(encryptedData, 'base64'); // 算法为 AES-128-CBC，补位方式为 PKCS#7 const decipher = crypto.createDecipheriv('aes-128-cbc', key, ivBuf); decipher.setAutoPadding(true); let decoded = decipher.update(dataBuf, null, 'utf8'); decoded += decipher.final('utf8'); return JSON.parse(decoded); }

几个必须对齐的点，我用列表单独强调，因为每一条我都见过有人栽：

• 算法固定：对称加密的算法模式是固定的，别自己换，换了必然解不开。
• 密钥长度：会话密钥解码后是固定长度的字节序列，如果长度不对，说明你在传输或存储过程中把它弄坏了（比如被 JSON 序列化截断、被某些框架转义）。
• 自动补位：补位方式是标准的那一种，绝大多数库默认就开着，别手动关掉。
• 统一编码：三要素全部按同一种编码处理，全 Base64 进、全 Buffer 出，中间不要混。

4.3 解密后拿到的到底是什么结构

解密成功之后，你会得到一个 JSON 对象，里面包含一个数组和若干元信息。数组的每个元素代表某一天的步数记录，字段大致包括日期、步数、以及一个表示数据来源的标记。

这里有个容易误判的点：数组长度不固定。它只包含你请求的那个时间窗口内、且确实有数据的那些天。如果用户某天没带手机、或者设备没同步，那一天就不会出现在数组里。所以前端展示时不能假设"数组第 0 位就是今天"，必须按日期字段去匹配，否则展示出来的日期和步数会对不上。

我一般会在服务端做一层整理：把数组转成以日期为键的映射，再按业务需要补齐缺失的日期（补 0 或者标记为无数据）。这样前端拿到的结构是稳定的，不用在页面里写一堆容错逻辑。

5. 真机与工具环境差异：那些"本地好好的"的坑

5.1 模拟环境为什么不可信

开发者工具为了调试方便，对不少能力做了"宽松处理"：可能不真的走授权流程、可能返回模拟数据、可能忽略某些前置条件。这导致一个非常典型的现象——工具里一路绿灯，真机上一片红灯。

我的经验是：只要涉及开放能力、用户授权、会话状态这三类东西，必须在真机上验证，工具里的结果只能作为参考。具体到步数这个场景，工具里可能直接给你一串看起来合理的密文，让你误以为链路通了，实际上真机上连授权都没弹。

所以调试节奏应该反过来：先真机跑通最小链路（登录 → 授权 → 拿密文 → 解密出明文），再回到工具里做界面和逻辑开发。别在工具里堆了半天功能，最后发现地基在真机上立不住。

5.2 授权被记住导致的"幽灵失败"

前面提过授权状态会被记住，这里展开说它的连锁反应。用户在真机上第一次点拒绝之后，你后续所有的调用都会失败，而且失败得毫无声息。更麻烦的是，这个状态在不同设备、不同账号上是独立的，你在 A 设备上复现不了 B 设备的问题。

排查时我的做法是：准备一个专门的"干净账号"，每次测授权相关逻辑前先确认它的授权状态。如果状态是脏的，就换账号或者引导重置，绝不在脏状态上继续调。这个习惯能帮你把"代码问题"和"环境问题"彻底分开。

注意：不要为了图快，在真机上反复点"拒绝"去测试异常分支。异常分支应该在代码里用条件控制来模拟，而不是靠污染真实账号的授权状态——那个状态很难清，清起来很麻烦。

5.3 时间窗口参数写错，接口会"成功但没数据"

这一条属于参数级细节，但杀伤力很大。请求数据时要指定一个时间范围，这个范围有约束：跨度不能太大，也不能是未来时间。参数写错了，接口不报错，直接给你一个空数组。

我自己中招过一次：把日期格式化成了带时区的完整字符串，接口认不出来，默默返回空。改成标准的日期格式之后就正常了。所以参数格式这类东西，一定要照文档的示例逐字符比对，别凭感觉写。

另外跨度也要注意。想一次拿很长的历史是不现实的，接口对窗口有硬性限制。合理的做法是分多次请求、按天聚合。如果业务确实需要长期数据，就得在自己的服务端做累积存储，而不是指望接口一次给全。

6. 一套能复现的排查顺序，别再瞎试

6.1 从症状反推链路的排查表

把前面所有内容收拢成一张可执行的排查表。遇到问题按这个顺序走，基本能在十分钟内定位到具体环节。

这张表的用法是严格按顺序，不要跳。我见过太多人一上来就怀疑解密算法，结果问题在第一步的后台配置。按顺序走，每一步都有明确的判定标准，能避免在错误的方向上浪费大量时间。

6.2 日志要打在关键节点上，而不是到处打

排查效率高低，很多时候取决于日志打在哪。我的习惯是在链路的四个节点各打一条结构化日志：登录完成、授权结果、密文长度、解密结果。

• 登录完成：记录是否拿到会话、会话是否已落库
• 授权结果：记录授权状态和返回的密文是否为空
• 密文长度：这是个很实用的信号，长度异常通常意味着数据被截断
• 解密结果：记录解密成功与否，失败时记录异常类型

这四条日志一摆出来，问题在哪一环几乎一目了然。比起在每个函数里都打日志、最后淹没在信息里，这种"关键节点打点"的方式效率高得多。而且日志里不要打密钥和完整密文，这是安全底线，只打长度和状态就够了。

6.3 一个最小可复现的验证脚本

最后给一个思路：在正式开发业务之前，先写一个最小验证脚本，只做"登录 → 授权 → 上报密文 → 解密 → 打印明文"这五步，不做任何界面。这个脚本跑通了，说明整条链路的地基是稳的，后面加业务功能才有意义。

这个脚本的价值在于隔离变量。业务代码里掺杂了太多逻辑，出问题时你分不清是链路问题还是业务问题。而最小脚本只有链路，成功就是成功，失败就是失败，判断极其干脆。我现在的习惯是每个涉及开放能力的项目，都先把这个脚本跑通存档，后面任何时候怀疑链路，直接拿出来复测，比在业务代码里大海捞针快得多。

关于频率控制再补一句：这类接口对调用次数是有约束的，别在调试时写成循环狂调，容易触发限制，反而拖慢排查。加上合理的节流和缓存，既是合规要求，也是工程习惯。

7. 写在最后的一点实际体会

这条链路我从头到尾捋过好几遍，最大的感受是：微信运动步数这件事，难点从来不在"拿到数字"，而在"把每一环的前置条件都摆对"。授权、会话、编码、参数，任何一环出偏差，表现都是同一句话——失败，而且往往不告诉你为什么。

所以真正省时间的做法不是背代码，而是把链路画清楚、把每一环的判定标准定下来。我现在遇到类似问题，第一反应不是改代码，而是拿出那张排查表，从上往下逐项过。十有八九，问题在第三、四行就被揪出来了，根本轮不到怀疑解密算法。

另外一个想说的是，别怕真机。工具里舒服，但真机才是真相。养成"先真机跑通最小链路"的习惯，能帮你省掉后面无数次的返工。这个习惯我吃过亏才养成的，希望你不用吃同样的亏。