简介支付宝小程序demo是一份面向小程序初学者的完整示例项目基于支付宝开放能力演示地图展示与扫码、用户授权获取头像昵称等个人资料、内置组件与自定义组件搭配调用等典型开发场景能帮助开发者快速理解从页面搭建、数据交互到业务功能落地的整体流程。资源共400个文件压缩包大小394KB以acss样式文件、js逻辑文件、axml页面结构文件和json配置为主同时包含utils工具类及项目配置目录结构清晰便于按模块对照学习。已有1833人学习下载。通过该demo可以掌握地图API与扫码接口的接入方式如导航至指定位置、扫描二维码获取信息熟悉用户信息授权流程与隐私合规要点学习组件复用方法并参考comti-ali包名下的工程组织方式覆盖初始化项目、模拟器与真机调试、性能优化到审核发布的完整开发链路为后续实现导航、扫码支付、信息采集等功能提供可直接借鉴的实践模板适合正在入门支付宝小程序或需要搭建基础框架的开发者参考。1. 项目概述与整体设计思路1.1 为什么要做这个支付宝小程序demo先聊点实在的。小程序这个赛道微信先跑起来但支付宝小程序的市场份额一直不低尤其电商、生活服务、政务办事这几个类目支付宝的场景反而更深。很多做前端的朋友微信小程序写熟了第一个反应就是“我是不是可以无缝平移过去”——我只能说想得太美了。我在接到“支付宝小程序demo”这个需求时核心目标很明确用最短的时间跑通一个包含页面跳转、数据请求、表单交互、组件复用的小型项目用来验证支付宝小程序开发链路是否顺畅同时沉淀一套可以被后续业务复用的工程模板。这个demo不需要有多复杂的业务逻辑但它必须覆盖到支付宝小程序与微信小程序之间那些“看似一样、实则不同”的细节——这些差异坑踩过一次就知道有多痛。另一个现实需求来自团队内部不止一个人问过“uniapp项目运行支付宝小程序失败”的问题。这个问题我在后面专门花一节来讲因为它的排查思路比问题本身更有价值。1.2 技术选型原生还是跨端框架做支付宝小程序面前有两条路直接用原生框架或者用uni-app / Taro这类跨端方案。我这次选的是原生。原因有两条第一demo的体量很小总共就三五个页面原生的开发效率在这个体量下并不低第二也是更重要的——只有写一遍原生你才能真正理解支付宝小程序的生命周期、API设计和性能模型。跨端框架给你的是“一瓶水”但你想知道瓶子里水的来源还是得回过头来看原生的实现。但是我不反对跨端方案。如果你团队里有现成的uni-app工程并且未来要同时发微信、支付宝、H5多端那uni-app是完全合理的选型。只是你要有心理准备跨端框架生成的支付宝小程序在基础库兼容性和部分组件行为上会比你预期的更“微妙”。这里我先把结论放在前面无论选哪条路demo的最终形态都应该是一个可以被团队其他人快速打开、点击、理解的项目。它不是玩具是沟通工具。1.3 页面结构与功能范围规划我的demo规划了4个页面不多但每一页都有目的首页index展示产品信息列表模拟请求后端接口并渲染同时包含一个搜索框为后面的输入框问题做准备。列表页list从首页点击进入展示更多筛选条件验证页面参数传递。表单页form完整的表单交互包含输入、选择器、日期选择、提交按钮后面实践了“input只读”的坑。我的页mine展示用户状态包含一个登录按钮模拟登录以及一个四级联动选择器这个后面会细说。功能边界上我没有做支付毕竟demo不需要真的拉起收银台没有做消息推送没有做分包加载。这些是业务项目的事demo阶段只需要把“骨架”立起来就行。2. 环境准备与工程初始化2.1 开发者工具下载与项目创建支付宝小程序开发需要用到官方IDE名字叫“支付宝小程序开发者工具”。下载安装之后用支付宝账号扫码登录即可。这里有一个细节容易被忽略首次登录后必须在“设置”里确认自己的角色有开发权限如果没有后面上传代码、预览真机都会报错。新建项目时有几个选项模板选择、后端服务选择、目录结构。我建议全部选最简配置——空模板不要选那些带云开发的demo阶段用不到还会多出一堆看不懂的文件。AppID这一栏新手可以先用测试号工具会提示你申请不用急着注册企业账号。测试号在真机预览、接口调试上基本够用。我之前见过有人因为“没有AppID”卡了一天其实申请一个测试号十分钟就能搞定。2.2 初始化目录结构与全局配置支付宝小程序的目录结构第一眼看上去和微信很像但仔细看会发现不少差异├── app.js // 全局逻辑 ├── app.json // 全局配置 ├── app.acss // 全局样式对应微信的app.wxss ├── pages/ │ ├── index/ │ │ ├── index.axml │ │ ├── index.js │ │ ├── index.acss │ │ └── index.json │ ├── list/ │ ├── form/ │ └── mine/ └── utils/ └── request.js // 封装请求这里最需要适应的就是模板文件的扩展名是.axml样式文件是.acss配置还是.json。别问为什么不是.wxml没有为什么生态不同。全局配置app.json的结构大体如下{ pages: [ pages/index/index, pages/list/list, pages/form/form, pages/mine/mine ], window: { defaultTitle: 支付宝小程序Demo, titleBarColor: #1677ff, pullRefresh: false }, tabBar: { items: [ { pagePath: pages/index/index, name: 首页 }, { pagePath: pages/mine/mine, name: 我的 } ] } }注意几个不一样的地方支付宝小程序的导航栏标题字段是defaultTitle而不是navigationBarTitleTexttabBar的字段是items数组而不是list数组图标不是必填项可以只显示文字。这些差异如果不实际跑一遍单看文档很容易记混。2.3 一个必须注意的目录规划细节还有一个小坑支付宝小程序的页面目录和微信一样支持分包加载但demo阶段不建议开分包。原因很简单分包模式要求主包和分包都各自配置app.json文件层级变复杂排查问题的时候多一层概念负担。等你后面做正式项目、单个包体超过2MB再回来折腾分包时间上更划算。我见过不少新手把页面的路径写错——app.json里的页面路径必须以pages/开头且不能包含扩展名。写错之后工具会提示“页面文件不存在”但有时提示并不直接可能只是白屏。3. 核心页面开发与关键技术点3.1 AXML模板语法与数据绑定在支付宝小程序里axml模板文件负责页面结构。它的数据绑定语法和微信的wxml高度相似view classproduct-card onTaphandleProductTap>view a:for{{productList}} a:keyid classproduct-item {{index}}: {{item.title}} /viewa:key这里必须给而且必须是一个唯一标识。我之前不写a:key在列表数据更新时出现了渲染错位的问题查了很久才定位到是列表复用机制导致的。条件渲染同样语法有变化微信是wx:if支付宝是a:if。我自己写的时候已经习惯成自然但每次从微信项目切过来总会手滑写错一两个建议你在模板里做一次全局搜索排查。3.2 页面生命周期与onLoad参数接收支付宝小程序的页面生命周期和微信几乎一一对应onLoad、onShow、onReady、onHide、onUnload。在列表页接收参数是demo中必测的功能Page({ onLoad(query) { // query是页面跳转时携带的参数对象 console.log(接收到的参数, query); this.setData({ categoryId: query.categoryId }); this.fetchList(); }, data: { categoryId: , listData: [] }, fetchList() { // 请求数据并setData } });有一个面试时爱问的细节onLoad里第一次setData是不需要刷新的页面还没有渲染数据直接放入初始渲染即可。但如果在onReady之后setData就会触发整个页面的视图更新需要关注性能问题。页面间跳转的方式也有讲究。框架提供了my.navigateTo跳转并保留当前页、my.redirectTo替换当前页、my.switchTab切换tab页、my.navigateBack返回上一页四个常用API。demo里我从首页跳列表页用的navigateTo从首页tab跳到“我的”用的是switchTab因为navigateTo无法跳转到tabBar页面这个限制在微信里也有。3.3 支付宝小程序input只读的三种实现方式这个点我要特别拿出来说因为热词里有“支付宝小程序 input 只读”说明踩这个坑的人不少。需求很常见表单某个字段不允许用户修改只能通过其他交互比如选择器、日历来赋值。实现方式无非三种方式一给input加disabled属性。这是最直接的方案但有一个副作用——被禁用的input在视觉上通常会变灰不同基础库版本表现还不一样有的版本甚至不支持禁用样式定制。方式二使用readonly属性。支付宝小程序从某个基础库版本开始支持这个属性和HTML里的readonly语义一致只读但保留原样。实测下来这个方案最接近“只读”的语义。方式三不渲染input改用一个view来展示值。这是最“土”但也最不会出问题的方案。它的代价是你需要额外写样式并且在点击时手动触发真实输入框的聚焦逻辑。我最终选择的是方式二但在代码里加了一个兼容判断检测到基础库不支持readonly时降级到方式一input value{{formData.date}} readonly{{isReadonly}} placeholder请选择日期 disabled{{!isReadonly}} /这里有个细节如果你同时设置了disabled和readonly某些版本会有冲突。建议用状态变量控制不要写死属性这样后续调试时可以通过调试工具动态切换值。3.4 四级联动选择器的实现“支付宝小程序四级联动”在热搜词里出现也是电商业务里的一个高频需求省市区街道或者分类子分类子子分类具体项。支付宝小程序提供了picker-view和picker-view-column组件。四级联动的本质就是四个并排的滚动列每一列的数据根据上一列的选择动态变化。我实现的思路如下将四列数据源维护在同一个对象中用id关联。监听onColumnChange事件只处理“当前改动的是第几列”。当第1列变化时重置第2、3、4列的数据和第3、4列的选择项当第2列变化时重置第3、4列以此类推。使用setData一次性更新所有关联数据减少多次渲染。核心代码结构大致是onColumnChange(e) { const { column, value } e.detail; if (column 0) { // 更新第二列数据源重置第三、第四列 this.setData({ cityList: this.getCities(value), districtList: [], streetList: [], value: [value, 0, 0, 0] }); } // ... }这个逻辑本身不复杂真正考验人的是数据源的组织方式。网上有不少现成的省市区数据源但街道数据很少需要自己采集清洗。我这边的做法是先从公开的行政区划数据中拿到省市区街道层用了一些业务自定义数据冒充——demo阶段足够用正式项目需要根据业务实际维护。3.5 网络请求封装与拦截器支付宝小程序的网络API是my.request和微信的wx.request非常像但有几个细节差异一是my.request的success回调里拿到的返回值结构不同后端返回的数据在res.data下面二是支付宝的my.request默认不携带cookie和微信一样三是域名必须在支付宝开放平台配置合法域名否则只能在开发者工具里关闭域名校验来做真机调试官方不推荐但demo阶段是真的方便。我封装了一个简易的request.js支持统一的header注入、错误码拦截、loading统一管理。核心代码其实很短function request(options) { const token my.getStorageSync({ key: token }).data || ; return new Promise((resolve, reject) { my.request({ url: options.url, method: options.method || GET, data: options.data || {}, headers: { content-type: application/json, Authorization: Bearer ${token}, ...options.headers }, success: (res) { if (res.status 200) { resolve(res.data); } else { reject(res); } }, fail: (err) { reject(err); } }); }); }在实际业务中还有一点需要处理请求的统一错误提示。我在reject之前会弹一个my.showToast这样页面层就只需要关心业务数据逻辑不需要每个请求都写一遍兜底。4. 常见问题与排查技巧实录4.1 uniapp项目运行支付宝小程序失败的排查思路这个热词排名很靠前我猜不少人遇到了。其实“失败”只是表象具体原因千奇百怪我把常见的几种情况汇总成了一个速查表症状可能原因解决建议编译直接报错uniapp项目缺少支付宝小程序编译插件在HBuilderX中安装相应的插件“支付宝小程序”编译插件重新编译运行后白屏首页路径配置错误或AppID未配置检查pages.json中的首页路径确认示例AppID是否正确部分组件不渲染uniapp编译后的组件与支付宝基础库不兼容检查是否使用了仅微信支持的组件如cover-view的某些属性需要做条件编译请求失败合法域名未配置或本地关闭了域名校验在开发者工具详情中勾选“不校验合法域名”或到开放平台配置白名单真机预览异常基础库版本过低在开发者工具中切换基础库版本至少使用2.x以上我自己实际碰到最多的是第一类——编译插件缺失。很多人以为HBuilderX自带全部平台编译能力其实不是。你需要到插件市场拉取“支付宝小程序”编译插件安装之后项目右键菜单里才会出现“运行到支付宝小程序模拟器”的选项。另外还有一个非常细的坑uniapp项目里如果你用了uni.setNavigationBarTitle这类API编译到支付宝小程序后被翻译成my.setNavigationBarTitle但支付宝的API名有时和微信不完全一一对应导致API调用无效。这种问题只能逐个排查具体API可以用条件编译分开处理。4.2 列表渲染数据更新不刷新问题这个问题的现象是setData执行了但页面没有更新。排查半天最后发现是setData的路径写错了。支付宝小程序和微信一样支持路径表达式更新数据this.setData({ productList[0].title: 新标题 });但如果你直接写this.setData({ productList: newArray })并且newArray引用没变某些基础库版本可能不会触发视图更新。解决办法是每次操作数组时返回一个新数组不要在原数组上push或splice后直接赋值。这算是JavaScript引用类型的一个经典问题。在React里大家已经被多次教育要不可变数据在小程序里同样的教训再演一遍。所以我建议你在utils里封装一个数组更新函数降低心智负担。4.3 真机预览时样式错乱样式在开发者工具上一切正常一上真机就乱了这在Web开发里是家常便饭小程序也不例外。最常见的问题rpx单位适配。支付宝小程序的rpx和微信的rpx定义不同微信里是750rpx等于屏幕宽度支付宝也是750rpx但不同设备的换算结果可能有细微差异导致某些元素的宽度在部分机型上溢出。另一个高频是flex布局的默认值差异。在开发者工具自带的浏览器内核里align-items的默认值可能是stretch但到了真机的渲染引擎上表现一致吗实测下来支付宝小程序的基础库对flex的兼容逻辑与微信基本一致但如果你在axml里嵌套了多层view而没有显式设置display: flex的容器某些Android机型上会出现间距异常。遇到这类问题我的建议是在写样式时尽量减少对默认值的依赖每个关键容器都显式设置display和flex-direction。4.4 输入框聚焦后页面被顶起的处理表单页里有一个搜索框和几个输入项在真机上测试时发现输入框聚焦后整个页面会被键盘顶起来甚至页面底部的内容跑到屏幕中间。支付宝小程序的解决方案是配置adjust-position属性input adjust-position{{false}} ... /或者直接监听my.onKeyboardHeightChange来自动调整页面位置。如果业务场景简单直接设置adjust-position为false自己在页面底部留出安全区域即可。这个坑在demo阶段提出来主要是为了让你有个概念小程序的键盘交互比普通H5页面要复杂真机调试是必须的环节千万别只在开发者工具里跑一遍就交付。4.5 关于demo程序和第三方demo移植的补充热词里还出现了“demo程序”“ina228 demo板”“steam unity demo游戏”这些。虽然和支付宝小程序没有直接关系但我想顺带说一句看别人demo代码的正确姿势是不要先跑起来而是先看依赖、看目录、看配置。我拿“newland printdemo原厂demo”举例——很多硬件厂商提供的demo代码质量参差不齐有的甚至连注释都没有。移植到自己的项目时你只需要提取核心API调用和初始化的时序不要图省事把整个demo目录直接拷进主工程。照搬别人的demo看着跑通了实际埋了一堆无用的依赖后面维护起来会让你怀疑人生。5. 实操总结与个人经验5.1 从demo到正式项目还需要补什么这个demo跑通之后我只是验证了开发链路真正要演进成正式项目下面这几件事是绕不开的视觉规范demo里没有视觉设计直接用系统默认样式。正式项目需要落地设计规范包括色彩、字号、间距、组件库。状态管理如果页面间交互复杂或需要跨页面共享状态建议引入mobx-miniprogram或自己维护全局状态。支付宝小程序没有内置的全局状态管理方案这一点和微信一致。构建流程原生的支付宝小程序没有内置的代码压缩、环境变量管理机制需要引入外部构建工具来做多环境配置。如果不想自研可以看看ide里是否自带上传前压缩选项。埋点与监控至少要有页面访问统计和JS错误收集。支付宝小程序有my.reportAnalytics可以做基础埋点错误监控暂时没什么特好的方案一般通过my.onError配合服务端接收。测试支付宝的开发者工具本身就支持简单的路由调试但更完整的自动化测试一般是通过miniprogram-simulate等第三方库来完成。demo阶段至少人工过一遍关键路径。5.2 踩坑之后的一些个人体会最后私心分享几条我在这次demo开发里最想记住的经验。第一条别拿写网页的思路写小程序。网页里一个div不够就再包一层小程序里每个view都是有成本的——节点数、渲染性能、数据监听深度都受影响。能用一个view解决的不要嵌套三层。第二条官方文档常看常新但要注意版本。支付宝小程序的文档改版过好几次不同年份的图片和说明可能对不上号。搜索问题时优先看官方文档当前的版本别把2019年的一篇博客内容当作现在的基础库行为。第三条真机永远是最后一道关卡。开发者工具虽然提供了模拟器但它本质上是基于浏览器的模拟环境与真机的渲染引擎、系统键盘交互、网络环境都存在差异。所有关键页面都应该至少在一台Android和一台iOS真机上跑一遍再宣称“开发完成”。第四条demo也要讲基本法。这里的“基本法”指的是目录结构、命名规范、模块划分。demo虽小但每一个文件都应该归位。因为你不知道这个demo什么时候就会被拿去当模板、被扩展成正式项目。到那时候你前期留下的每一处混乱都会变成后人的眼泪。做技术这一行很多时候拼的不是创意而是对细节的敬畏。一个demo项目做得干不干净看代码就知道。希望这篇实操记录能帮你少踩几个坑回头你也能攒出一套自己的心得体会来。本文还有配套的精品资源点击获取
