简介围绕微信小程序扫码获取快递单号这一典型场景提供可直接运行的完整项目源码面向小程序初学者与快递查询类应用开发者演示从扫码授权、二维码解析到快递状态查询的完整链路。资源包共14个文件以json配置、js逻辑、wxml和wxss页面样式为主包含1个png扫码图标rar压缩包整体仅15KB轻量小巧便于导入开发者工具快速查看。已有3449人学习浏览。项目源码清晰划分页面与工具模块覆盖wx.scanCode调用、二维码Base64或正则解析、wx.request与后端/快递API交互、loading与错误提示等实现细节通过app.json、project.config.json及express、logistics等页面文件可直观学习小程序工程结构、扫码结果分流与数据展示方式适合直接复用或改造为自己的快递单号查询工具。1. 扫码拿单号从 wx.scanCode 到物流状态的链路在物流、仓配和线下单据核销场景里「扫一下二维码就直接出来快递轨迹」是最常见的需求之一。KuaidiSaoma 这个示例项目把链路完整串起来小程序端用wx.scanCode调起相机识别二维码里的文本或 URL解析出快递公司和运单号再通过wx.request交给 Node.js 的 Express 服务。后端拿到单号后对接快递查询 API把轨迹整理好回传给小程序渲染。流程看着简单但每个环节都有边界情况二维码内容格式不统一、运单号大小写需要兼容、第三方快递 API 的状态码需要统一转换。下面按「前端解析 → 服务端中转 → 列表渲染 → 联调排错」的顺序拆解整个实现适合正在做小程序扫码类功能、以及想理解小程序与 Node.js 协作的开发者。新手可以直接复现有经验的可以重点看后端的缓存与频控处理。2. 前端解析wx.scanCode 参数与二维码内容解构2.1 为什么扫码不需要申请权限很多刚接触小程序的开发者会误以为wx.scanCode需要在app.json里声明scope.scan。实际上这是个认识误区。wx.scanCode是用户点击后调起相机微信端会单独处理摄像头权限不需要像scope.userInfo那样提前声明授权。项目里真正需要配置的是permission.scope.camera它只影响弹窗文案{ permission: { scope.camera: { desc: 需要访问摄像头用于扫描快递二维码 } } }在页面中调用时只需要一个按钮绑定方法。常见写法如下// pages/express/express.js scanExpress() { wx.scanCode({ onlyFromCamera: false, scanType: [qrCode, barCode], success: (res) { const parsed parseExpressCode(res.result); if (!parsed) { wx.showToast({ title: 未识别到快递单号, icon: none }); return; } this.queryLogistics(parsed); }, fail: (err) { console.warn(用户取消扫码或摄像头不可用, err); }, }); }onlyFromCamera设为false表示除了调起相机还允许用户从相册选图识别这对二维码污损、拍摄角度不对的情况是个兜底。scanType同时开启二维码和条形码快递面单上两种码都会出现。参数说明res.result是扫码得到的原始字符串可能是链接、纯数字或自定义文本res.scanType是一个枚举值常见返回QR_CODE或CODE_128一般不会用在这段逻辑里。如果业务需要区分码制可以把它记进日志为后续排查用户现场提供依据。wx.scanCode常用返回字段可以用这个表来理解字段说明result二维码/条形码中存储的原始内容scanType识别的码类型如 QR_CODE、CODE_128charset部分 Android 设备返回的字符编码errMsg成功返回scanCode:ok成功回调里不要直接拿result去请求接口因为二维码里的内容没有固定结构必须先做一层解析。2.2 解析二维码内容中的公司编码和单号二维码内容在实际现场通常有三种形态。第一种是纯数字运单号例如75823456789012第二种是带公司前缀的自定义文本例如ZT|75823456789012第三种是一段 URL例如https://api.kuaidi.com/?comzhongtongnum75823456789012。如果用的是菜鸟或快递面单偶尔还会遇到前面带KUAIDI:标识的字符串。针对这些情况建议把所有解析逻辑收敛到一个纯函数中方便单独测试function parseExpressCode(raw) { if (!raw || typeof raw ! string) return null; // 去掉常见前缀标识 const body raw.replace(/^[A-Z]\s*[:|]\s*/i, ); // 形态一公司编码 分隔符 单号 const custom body.match(/^(zhongtong|yuantong|shunfeng|yunda|ems|zto|yto|sf|yd)[|:#\s]([0-9A-Za-z]{8,32})$/i); if (custom) { return { com: custom[1].toLowerCase(), num: custom[2].toUpperCase() }; } // 形态二URL query 中的 com 和 num const com getQueryValue(body, com) || getQueryValue(body, expressNo); const num getQueryValue(body, num) || getQueryValue(body, orderNo); if (com num) { return { com: com.toLowerCase(), num: num.toUpperCase() }; } // 形态三纯数字公司编码交给服务端判断 if (/^\d{10,15}$/.test(body)) { return { com: , num: body }; } return null; } function getQueryValue(url, key) { const re new RegExp([?] key ([^#]*), i); const match url.match(re); return match ? decodeURIComponent(match[1]) : ; }逻辑说明先去掉KUAIDI:这类前缀再用三种解析策略依次尝试。正则里的[|:#\s]表示公司标识和单号之间可以由管道符、冒号、井号或空白字符分隔适配不同打印模板。toUpperCase()是为了统一单号格式部分快递接口对字母大小写敏感提前统一能减少查询失败。注意这里的分隔符解析用的是自定义匹配如果现场二维码格式和示例不一样只需要加新的分支。几个关键参数说明getQueryValue里为什么不用URL对象因为小程序基础库对URL的兼容性不一致iOS 上可用但部分安卓机型老旧基础库会报错用正则解析 query 更保险。num的8,32长度范围覆盖国内运单号的常见长度。如果扫到一维码是 7 位说明可能是内部单号这种直接抛给后端做模糊查询反而容易误判。纯数字形态让com为空不是偷懒而是把公司识别放在服务端因为单一正则很难覆盖顺丰、申通、韵达等所有面单规则。如果现场二维码的文本是 Base64 编码的快递内容尽量不要在小程序里用atob硬解因为旧基础库没有这个全局函数。可以放到服务端解码再复用同一套解析函数。到这里前端已经把二维码内容解析成了{ com, num }结构下一步就是把它交给服务端。3. 服务端中转Express 封装快递查询接口3.1 为什么查询逻辑不能直接写在小程序里如果在小程序端直接调快递公司 OpenAPI首先会遇到密钥暴露问题。第三方快递接口的密钥放在前端等于公开反编译小程序代码就能看到。其次是域名限制微信小程序正式环境要求请求域名已经备案并支持 HTTPS而很多快递公司的 API 域名并不方便直接配置到合法域名列表里。所以示例项目单独开了一个express目录用 Node.js 做一层中转服务。小程序只把{ com, num }发到自己的服务由服务端携带密钥完成签名、请求、错误转换再把结果返回。核心服务代码const express require(express); const axios require(axios); const crypto require(crypto); const app express(); app.use(express.json()); const EXPRESS_QUERY_URL process.env.EXPRESS_QUERY_URL; const EXPRESS_APP_KEY process.env.EXPRESS_APP_KEY; app.post(/api/express/query, async (req, res) { const { com, num } req.body || {}; if (!num) { return res.status(400).json({ code: 400, message: 运单号不能为空 }); } const requestData { com: com || guessExpressCompany(num), num, }; const sign crypto.createHash(md5) .update(${num}${EXPRESS_APP_KEY}) .digest(hex); try { const remote await axios.post( EXPRESS_QUERY_URL, { ...requestData, sign }, { timeout: 5000 } ); res.json(remote.data); } catch (err) { console.error(快递查询失败, err.message); res.status(502).json({ code: 502, message: 快递查询服务暂时不可用 }); } });逻辑说明先校验num非空再根据是否传入com决定是否需要服务端猜测快递公司。签名用num appKey的 MD5这只是一个通用示例真实接入时要以第三方文档为准。axios请求设置 5 秒超时避免快递接口长时间不返回导致小程序端一直转圈。失败分支里统一返回502不暴露内部栈信息避免把服务端代码结构泄露出去。参数说明EXPRESS_QUERY_URL和EXPRESS_APP_KEY从环境变量读取不写死在代码里。上线后可以通过pm2或容器平台注入环境变量不同环境用不同密钥方便隔离。第三方快递接口通常需要以下参数接入前先核对文档参数名是否必选说明com条件必选快递公司编码如 zhongtong、shunfengnum必选运单号phone部分必选顺丰查询需要收件人手机号后四位sign必选签名串通常由密钥参与生成顺丰的场景比较特殊。用户扫码后拿不到收件人手机号时可以不做溯源单号直接返回state2提示用户去微信「顺丰速运」小程序内查询避免无效请求打到顺丰接口。3.2 用内存缓存和频控挡掉重复查询扫码场景下同一个运单号短时间内被反复扫的概率很高。如果每次都穿透到第三方接口既消耗接口配额又让用户等待时间变长。最常见的解决方案是给服务端加一层 TTL 缓存。示例项目用node-cache做进程内缓存const NodeCache require(node-cache); const trackCache new NodeCache({ stdTTL: 300, checkperiod: 60 }); app.post(/api/express/query, async (req, res) { const { com, num } req.body || {}; if (!num) return res.status(400).json({ code: 400, message: 运单号不能为空 }); const cacheKey ${com || auto}:${num}; const cached trackCache.get(cacheKey); if (cached) return res.json(cached); try { // 实际请求第三方快递接口的完整实现 const requestData { com: com || guessExpressCompany(num), num }; const remote await axios.post(EXPRESS_QUERY_URL, requestData, { timeout: 5000, }); trackCache.set(cacheKey, remote.data); res.json(remote.data); } catch (err) { console.error(快递查询失败, err.message); res.status(502).json({ code: 502, message: 快递查询服务暂时不可用 }); } });stdTTL: 300表示缓存存活 300 秒checkperiod: 60表示每 60 秒定期清理过期键。这组参数适合物流查询场景快递轨迹 5 分钟内通常不会大变化超过 5 分钟再重新查询即可。注意进程内缓存只对单实例生效如果用云托管或 K8s 部署了多个副本需要换成 Redis 做统一缓存层。这里的示例代码在拿到remote.data之后立刻写入缓存可以避免相同单号的并发请求同时穿透。除了缓存还需要加一层限流。可以用express-rate-limit针对扫码接口做限制const rateLimit require(express-rate-limit); const scanLimiter rateLimit({ windowMs: 10 * 1000, max: 5, message: { code: 429, message: 查询太频繁请稍后再试 } }); app.post(/api/express/query, scanLimiter, async (req, res) { // 查询逻辑 });windowMs和max取值不是固定的。手持 PDA 批量扫件时一个网点的 IP 可能在几十秒内发起几十次请求10 秒 5 次会误伤。建议先统计现场扫码频次再决定阈值如果担心被刷可以限制同一num的重复请求而不是单纯限制 IP。提示第三方接口的500/502响应不应写入缓存。只有拿到合法的行为轨迹时才调用trackCache.set否则用户会持续看到旧的失败信息。4. 物流轨迹展示WXML 列表与交互细节4.1 先规整数据再 setData后端返回的物流轨迹通常是嵌套对象直接放进setData会让 WXML 很难维护。示例项目里在小程序端做了一个字段规整只提取要展示的部分function normalizeExpress(resData) { const data (resData resData.data) || {}; const traces Array.isArray(data.traces) ? data.traces : []; const latest traces[0] ? ${traces[0].time} ${traces[0].desc} : 暂无轨迹; return { com: data.com || , num: data.num || , traces: traces.slice(0, 20), latest, }; }traces保留时间倒序第一项就是最新物流节点。slice(0, 20)限制单次渲染 20 条避免一次性把上百条轨迹铺进页面造成首屏渲染变慢。如果用户需要看全量轨迹可以再加一个“展开全部”按钮点击后重新拉取完整列表。这个切片不是数据截断而是控制渲染层的数据量后端接口里仍然保留了完整轨迹。在页面里调用queryLogistics(parsed) { this.setData({ loading: true, errorMsg: }); wx.request({ url: https://yourdomain.com/api/express/query, method: POST, data: { com: parsed.com, num: parsed.num }, success: (res) { this.setData({ loading: false, ...normalizeExpress(res.data), }); }, fail: () { this.setData({ loading: false, errorMsg: 网络异常请重试, }); }, }); }逻辑说明发起请求前先把loading置为true请求成功后用normalizeExpress的结果拼接到setData。这里用展开运算符把com、num、traces、latest都挂到页面数据上。参数说明wx.request的success不代表业务成功最好在normalizeExpress里判断res.data.code如果code不是 200 就返回空轨迹并给出提示不强制每个接口都返回 HTTP 200。4.2 条件渲染与状态码映射WXML 里用wx:if判断空数据用wx:for循环渲染轨迹列表view classtrack-card view wx:if{{traces.length 0}} classempty 没有查询到物流信息 /view view wx:for{{traces}} wx:keytime classtrack-item {{index 0 ? active : }} view classtrack-time{{item.time}}/view view classtrack-desc{{item.desc}}/view /view /viewwx:key使用轨迹时间字符串物流时间在单条轨迹里基本不会重复。首条轨迹加activeclass可以在样式里用左侧时间轴圆点高亮最新节点。注意wx:if和wx:for不要放在同一个节点上否则每次循环都会执行条件判断性能差。示例中用外层view做空状态判断内层view做循环。后端返回的状态码需要映射成用户能看懂的文案。快递 API 的状态码定义不一致统一在服务端转换一次更好小程序端只接收标准化状态state前端展示场景说明0运输中快递已发出且在途中1已揽收快递员已取件2请联系快递员包裹停留过久或地址问题3已签收正常签收4已退回寄件人收到退回件如果小程序端直接拿第三方原始状态码展示用户会看到“搜索中”“到达派件城市”之类不统一的语句。标准化的做法是在服务端做一个state到message的映射表示例里只画了 5 档实际可以按业务细分到 7 档。4.3 加载中状态和重试入口用户扫码之后网络请求可能需要 1 到 3 秒这期间页面不能白屏。除了顶部 loading 动画最好在列表区域也放一个显式的状态提示。示例中使用view wx:if{{loading}} classloading view classloading-icon/view text正在查询物流轨迹.../text /view view wx:if{{errorMsg}} classerror text{{errorMsg}}/text button sizemini bindtapreScan重新扫码/button /viewreScan直接复用scanExpress方法reScan() { this.setData({ loading: false, errorMsg: }); this.scanExpress(); }这里有个容易忽略的点当用户从错误状态点击「重新扫码」时需要先清空errorMsg否则新的扫码结果还没回来错误提示会一直留在页面上。scanExpress内部调用wx.scanCode时会再次拉起摄像头不需要重新进入页面。如果希望保留上一次查询的单号列表可以把这个页面设计成一个历史记录列表新查询结果插入到列表头部避免每次重扫都覆盖页面内容。5. 联调与排错抓包、模拟器扫码和常见陷阱5.1 模拟器与真机的权限差异微信开发者工具里点击编译按钮旁的「二维码」图标可以选择本地图片模拟扫码。模拟器不会触发摄像头权限弹窗wx.scanCode会直接返回图片中的内容适合快速验证解析逻辑。但摄像头权限、对焦速度、相册选图这些体验问题只能在真机上测。开发阶段可以在onLoad里查一下授权状态wx.getSetting({ success: (res) { if (!res.authSetting[scope.camera]) { // 引导用户点击授权按钮不要直接调用 openSetting console.log(尚未授权摄像头); } } });wx.getSetting返回的authSetting是只读的这里只是提前感知状态真正的授权发生在用户点击扫码按钮时。如果用户此前拒绝过可以在fail回调里引导到设置页。5.2 用 Charles 抓取小程序请求联调时最常遇见的问题是小程序请求能发出去但后端收不到或者响应结构不符合预期。用 Charles 可以观察完整的请求和响应链路。操作步骤在电脑上开启 Charles默认端口 8888同时开启 SSL 解密并安装证书到电脑手机 Wi-Fi 手动配置 HTTP 端口指向电脑 IP然后信任 Charles 证书。第一次抓 HTTPS 包时手机会提示证书未受信任需要在系统设置里找到「描述文件与设备管理」手动信任。抓包重点看三处wx.request发出的POSTbody 是否包含com和num以及Content-Type是否为application/json。服务端响应是否走了res.json()。如果用res.send(JSON.stringify(data))某些微信基础库会把响应识别为字符串开发者工具控制台会报Unexpected token错误。第三方快递接口的响应state是否在预期范围内避免把异常状态传入normalizeExpress。5.3 三处高频踩坑点第一二维码里带了中文前缀。常见内容是「快递单号75823456789012」直接用正则提取数字之前需要先按冒号拆分再取末尾的数字串否则正则会把「」后的空格带入num。推荐在parseExpressCode里增加一层body.replace(/^[^0-9A-Za-z]/, )清理不可见字符。第二顺丰查询需要手机号后四位。部分二维码并不包含手机号可以在页面里加一个二次弹窗让用户手动输入输入后拼到data里传给服务端再发起查询。第三后端签名算法不一致。不同快递平台签名字段排序规则不同有的要求参数按 ASCII 排序拼接有的要求 JSON 字符串转义后再加密钥。这些很容易在联调阶段漏掉。建议服务端把签名前的原始串先在代码里打日志和第三方文档逐字对比。最后如果你维护的是多个相同单号并发查询建议在app.post处理里加一层简单的 Set 去重相同num的请求只让第一个穿透到第三方接口其余复用同一次响应这比单纯扩大缓存 TTL 更有效。本文还有配套的精品资源点击获取