简介面向支付宝小程序开发者的示例工程适合零基础或刚接触小程序的前端开发者学习也适合需要快速搭建地图、扫码、用户信息授权等功能的团队参考。项目源码完整覆盖地图展示与扫码识别、获取用户头像昵称手机号、内置组件与自定义组件调用、页面数据绑定等常见开发需求并集中展示了支付宝小程序的典型目录结构与配置方式。压缩包共 400 个文件以 acss、js、axml、json 等核心源码文件为主另有 sample、png 等辅助资源包体仅 394KB结构紧凑便于逐文件阅读。目前已有 1833 人学习下载。通过该 demo 可以系统梳理开发工具安装、项目创建、页面编写、模拟器与真机调试、审核发布的全流程同时理解地图 API、扫码接口、用户隐私合规、性能优化等关键知识点可作为后续支付宝小程序项目开发的实用起步模板。 第一次点开支付宝小程序开发者工具的时候我心里想的是这跟微信小程序能差多少真做起来才发现组件写法、样式文件后缀、审核逻辑、API命名几乎处处有差异。这篇内容不是官方文档的复述而是我从零跑通一个支付宝小程序demo的全过程记录包括input只读为什么总不生效、四级联动怎么做、uniapp项目运行支付宝小程序失败怎么排查每一步都附了实际代码和操作思路。无论你是第一次接触小程序还是从微信小程序转过来的老手这篇都能帮你少走点弯路。1. 为什么我会建议先把支付宝小程序demo做出来1.1 从“会写页面”到“跑通全流程”很多人学小程序一上来就啃官网文档我的建议反着来先做一个能跑通的最小demo再回头补文档。原因很简单小程序开发里有一大半“坑”是只有把项目真正跑起来才会遇到的。比如你写了一个页面在微信小程序里正常显示搬到支付宝小程序里样式就乱了又比如你调接口时发现返回的数据结构没问题但登录态就是带不过去。这些都不看文档能解决的问题只有亲手做一遍才能建立印象。我做的第一个支付宝小程序demo很简单就是一个包含表单提交、列表展示、带筛选的页面跳转的小东西。功能加起来不超过三个但跑完这一圈我对整个开发链路就有底了从工具配置、项目创建、页面路由到接口联调、真机预览心里清楚每一步在哪里容易出问题。1.2 支付宝小程序区别于微信小程序的三个核心差异如果你有微信小程序的基础转入支付宝小程序时会发现几个明显的差异点。首先文件后缀不一样页面结构是.axml样式是.acss逻辑还是.js全局配置是.json。虽然axml和wxml的语法高度相似但属性名和事件绑定写法有差别比如循环用a:for而不是wx:for点击事件用onTap而不是bindtap。其次API的调用前缀是my不是wx。比如显示 toastmy.showToast()。如果你习惯了一个 API 字典转过来很容易顺手写错。第三点也是影响最大的一点支付宝小程序的开放能力侧重支付、芝麻信用、城市服务这一类。审核规则对这些能力有额外的要求和权限限制这在你规划demo功能时就要考虑进去不然做到后面发现某个能力申请不下来白费工夫。2. 从零搭建开发工具、工程结构和第一批页面2.1 账号、工具与一个demo的初始化开始动手前先去支付宝开放平台注册一个开发者账号然后在“小程序”板块里创建一个小程序应用拿到AppID。这个AppID后面到处要用不管是开发者工具里创建项目还是uniapp打包配置都离不开它。接着下载支付宝小程序开发者工具。这里要注意不要拿微信开发者工具将就两个工具不互通。安装登录后新建项目时选择“空白项目”填上刚才拿到的AppID再选一个本地目录工具会自动生成一套标准工程结构。如果你已经有一个现成的代码仓库也可以选择“导入项目”工具会自动识别.axml和.acss文件。2.2 app.json全局配置藏了很多“默认行为”打开新建项目的根目录你会看到一个app.json这是整个小程序的全局配置文件。页面路由、窗口样式、tabBar都在这里声明。我第一次做demo时忽略了一个细节支付宝小程序的窗口标题字段不叫navigationBarTitleText而是defaultTitle字面意思就是导航栏默认标题。如果你的页面没有单独配置标题这里设置的字符串就会统一生效。以下是一个最基础的app.json配置{ pages: [ pages/index/index, pages/form/form ], window: { defaultTitle: 我的支付宝小程序demo, titleBarColor: #1677ff } }注意两点pages数组的第一项就是启动页每新增一个页面都要手动在这里注册这是小程序开发绕不开的一步忘了注册的话页面永远打不开。2.3 第一个页面数据绑定、事件和调试页面文件放pages/index/目录下包含index.axml、index.acss、index.js三个文件如果不需要独立配置可以省掉index.json。页面逻辑很简单用data维护状态用setData更新视图事件绑定用onTap。下面是一个可以秒上手的示例view classcontainer text{{message}}/text button onTaphandleTap点我一下/button /viewPage({ data: { message: hello alipay }, onLoad(query) { console.log(页面参数, query); }, handleTap() { this.setData({ message: 点击成功 }); } });代码写完后点击开发者工具顶部的“编译”模拟器里就会渲染出这个页面。你可以打开开发者工具的调试器查看console.log输出这一点跟浏览器开发者工具很像小程序里排查问题主要靠它。这里有个小经验调试样式时不要把全部样式写在acss里先用开发者工具的样式面板直接在模拟器里调整调好了再回落代码。因为小程序样式的生效机制在某些属性上跟浏览器不完全一样比如部分媒体查询、伪元素支持有限先试后写会省很多时间。3. 表单与组件input只读这类坑是怎么来的3.1 只读字段的正确写法很多人在支付宝小程序里做表单页时会碰到一个需求某个输入框只展示数据不允许用户修改。第一次碰到这个问题直觉是给input加一个readonly属性。原生支付宝小程序的input组件确实支持readonly但有个细节很容易踩坑部分版本的渲染引擎中带readonly的输入框仍然会响应点击并弹出键盘只是键盘输进去的内容不会生效。如果不想让用户点击后有弹键盘的反馈更稳的做法是直接用disabled属性。副作用是disabled输入框的文本颜色可能会变成灰色有时不符合UI效果。这时我的处理方式是外面包一层view用disabled的input保持值展示同时自己控制样式覆盖文字颜色。你可以对比一下这两种写法!-- 只读但部分环境仍可聚焦 -- input value{{detailInfo}} readonly / !-- 完全不可交互适合纯展示场景 -- input value{{detailInfo}} disabled /在uniapp里写的话更要注意input组件本身不一定透传readonly你最好使用:disabledtrue这样的写法或者直接在条件编译里区分平台。3.2 表单里最常见的两个场景真实demo里只读字段通常出现在两种场景。一种是“详情页展示”场景用户打开一条记录查看大部分字段都是只读的。这种情况我建议别用input硬扛直接用text或者view渲染文本配合样式做成伪输入框的样子既省事又不会有键盘弹出的烦恼。另一种是“回显可改”的编辑场景字段根据某个开关状态在只读和可编辑之间切换。这时用disabled的动态绑定来实现最方便input value{{fieldValue}} disabled{{!editable}} /注意editable为true时可编辑为false时禁用逻辑更直观。同时提交时不要直接用input的value通过data里的fieldValue取值避免中间状态错乱。3.3 一个demo表单页的完整示例结合上面的思路我给出一个简单但完整的表单页代码片段。这个页面包含一个只读的用户名输入框和一个可编辑的备注输入框view classform-item text classlabel用户名/text input value{{username}} disabled / /view view classform-item text classlabel备注/text input value{{remark}} onInputhandleRemarkInput / /view button onTapsubmitForm提交/buttonPage({ data: { username: 张三, remark: }, handleRemarkInput(e) { this.setData({ remark: e.detail.value }); }, submitForm() { console.log(this.data.username, this.data.remark); // 这里发起提交请求 } });实际做的时候你会发现“只读”的关键不在于属性有多复杂而在于想清楚交互边界允许聚焦吗允许复制吗提交时包含这个字段吗这些问题想在前面代码自然简洁。4. 多级联动实战以四级联动为例拆解数据驱动4.1 四级联动比三级难在哪如果你用过头晕的城市选择器你应该知道三级联动省—市—区已经是很多前端开发者的心理阴影了。四级联动省—市—区—街道的复杂点不是多了一层循环而是数据处理要更讲究因为每一级的选择都会影响后面所有级的数据范围。初学时我试过把整个联动逻辑写在一个bindchange回调里结果代码膨胀得没法看。后来总结出一个思路用索引数组标识当前选中项用columns数组维护每列展示的数据联动时根据新的索引重新计算后面所有列数据。数据结构上我先在后端接口里拿到的数据是一个嵌套数组const regions [ { code: 110000, name: 北京市, children: [ { code: 110100, name: 北京市, children: [ { code: 110101, name: 东城区, children: [ { code: 110101001, name: 东华门街道 } ] } ] } ] } ];4.2 数据结构和联动逻辑核心思路是selectedIndex存四个数字分别对应四列的选中下标columns数组在页面启动时初始化为第一列的完整数据、第二列是regions[0].children以此类推。当用户滚动选择器触发bindchange时拿到新的索引数组从第一列开始判断如果第一列变了第二列的columns要换成新第一级对应的子级数据第三、四列跟着重置如果只是第二列变了第三、四列要重置。判断完成后把新的columns和selectedIndex一起setData。在axml模板里我一开始想用regions[selectedIndex[0]].children这样的动态下标但实测发现模板表达式支持有限且容易踩性能坑。正确做法是在data里维护好columns数组模板只管渲染。4.3 代码实现直接上可以跑的代码picker-view value{{selectedIndex}} bindchangeonColumnChange picker-view-column view a:for{{columns[0]}} a:keycode{{item.name}}/view /picker-view-column picker-view-column view a:for{{columns[1]}} a:keycode{{item.name}}/view /picker-view-column picker-view-column view a:for{{columns[2]}} a:keycode{{item.name}}/view /picker-view-column picker-view-column view a:for{{columns[3]}} a:keycode{{item.name}}/view /picker-view-column /picker-viewPage({ data: { regions: [], columns: [[], [], [], []], selectedIndex: [0, 0, 0, 0] }, onLoad() { // 假设已经拿到了嵌套数据 const regions getRegionData(); this.setData({ regions, columns: [ regions, regions[0].children, regions[0].children[0].children, regions[0].children[0].children[0].children ] }); }, onColumnChange(e) { const value e.detail.value; const regions this.data.regions; const [i0, i1, i2] value; const level1 regions[i0] || regions[0]; const level2 (level1.children level1.children[i1]) || level1.children[0]; const nextColumns [ regions, level1.children, level2.children, level2.children level2.children[i2] ? level2.children[i2].children : [] ]; this.setData({ selectedIndex: value, columns: nextColumns }); } });这里我顺便提一嘴不要迷信网络上那种十几行就能搞定联动的“极简代码”大多数忽略了数据为空、越界和默认选中这三类边界情况。demo阶段可以糙一点但逻辑结构要完整不然接真实数据时很容易出bug。5. 集成与调试uniapp跑支付宝小程序失败时的排查链路5.1 失败时先看编译日志现在不少项目是拿uniapp开发的一套代码同时编译到微信和支付宝小程序。理想很丰满现实很骨感我经常遇到“uniapp项目运行支付宝小程序失败”的情况。第一次遇到时有点慌后来总结出一条排查链路分享给大家。第一步永远是看编译日志。在HBuilderX里运行运行时控制台会输出具体的错误信息。常见的信息有“未配置支付宝小程序AppID”“找不到支付宝开发者工具”“编译失败: xxx文件不存在”等。看到错误先别跑大部分信息已经直接告诉了你原因。5.2 常见原因分类我把实际遇到的失败原因整理成一个表格方便你对照报错现象可能原因处理思路提示未配置AppIDmanifest.json里mp-alipay节点没填在支付宝开放平台创建小程序应用复制AppID填入无法打开支付宝开发者工具未安装工具或工具没有开启服务端口安装工具并在工具设置里开启调试相关开关编译后页面空白依赖了支付宝不支持的API或组件查uniapp文档替换为多端兼容写法样式完全乱了使用了条件编译或特定平台样式未适配在mp-alipay条件编译里补充样式自定义组件不显示支付宝小程序的组件路径大小写敏感检查组件路径、文件名是否完全一致这里要特别提醒一个新手容易忽略的点uniapp默认的编译模式是生成所有目标小程序代码如果你在运行时没有手动选择“支付宝小程序”编译器可能会把代码生成到微信小程序目录或根本不启动支付宝工具。在HBuilderX的“运行—运行到小程序模拟器—支付宝小程序”里明确选择一次很多问题会直接消失。5.3 真机调试编译通过不代表真机没问题。支付宝小程序开发者工具里一般有“真机预览”功能用支付宝App扫码就可以在手机上运行。我遇到的一个典型场景是开发者工具里一切都正常真机上接口却调不通。排查下来发现是没有配置合法域名真机环境下有严格的域名校验。解决思路是在支付宝开放平台后台配置服务器域名或者在开发阶段使用“开发调试”模式临时绕过。但注意上线前一定要把正式域名配好这是审核和稳定性的基础。另外真机上建议直接看手机的日志面板支付宝App支持vConsole之类的调试工具打开调试开关后会显示更详细的错误信息。6. 上线前别忘了这些事6.1 隐私协议、版本号和体验版demo跑通后很多人急着提交审核结果被平台打回来。我一个一个说。第一隐私协议。支付宝小程序对收集用户信息是有明确要求的如果你的demo里有登录、定位、信息采集这些行为必须在“设置-隐私协议”里写清楚收集了什么、怎么用。第二版本号。在后台配置版本时版本号要递增一般用1.0.0这种格式不要用“v1”“demo1”这种随意命名真到审核环节会被要求规范化。第三体验版。提交审核前建议先发布一个体验版邀请同事或朋友试用。支付宝小程序的体验版可以设置成员权限只有名单内的人能访问适合内测阶段。这一步能提前发现很多页面样式、接口权限、逻辑异常问题比提交审核后被拒来回折腾高效得多。6.2 从demo到产品我给新手的建议demo的意义是验证思路、跑通流程并不是产品的终点。如果你准备把一个demo演变成正式项目有几件事必须提前做把接口地址统一抽到配置文件不要散落在页面里包装好通用的请求类和错误处理逻辑登录态要做成全局管理而不是每个页面各写一套代码分包保证首屏加载速度。我个人的体会是demo阶段最忌讳闭门造车。同一个功能去开放平台社区、开发者论坛搜一搜能发现很多“比文档多走一步”的实战经验。比如input只读的问题官方文档只写了属性说明但实际交互反馈和不同平台的差异往往只在社区讨论里才看得到。动手做一遍再结合别人的经验会成长得非常快。本文还有配套的精品资源点击获取