你有没有过这种经历第一次打开微信开发者工具看到左侧那一堆文件夹和文件第一反应是不知所措。我带过的实习生里十个有九个都是从这里开始迷茫的。微信小程序的开发流程说穿了其实就六件事——注册账号、搭工程、写页面、通数据、调试排错、发布上架。这条全链路我完整跑过很多轮踩过的坑比写过的代码都多。今天就把整个流程掰开揉碎讲清楚包括那些总被问到的列表分页加载、顶部导航高度适配、订阅消息授权、包体积超限、真机调试分发等等一次性串起来。1. 账号注册与工具链准备选错主体类型后面至少多走半个月弯路小程序开发的第一步不是写代码而是把账号和工具打理好。这一步看似简单但其中注册的是个人主体还是企业主体这个决定会影响你后面能不能用支付、能不能上某些类目甚至影响审核通过率。1.1 个人主体和企业主体的核心差异打开微信公众平台点立即注册选小程序然后就会面临第一个选择个人还是企业。很多人随手选了个人做到一半发现需要微信支付回头改主体只能重新注册、重新走认证流程前面的代码全部换AppID相当痛苦。个人主体适合的学习项目和个人工具类产品比如记账本、菜谱查询这类不需要交易闭环的应用企业主体适合任何涉及支付、电商、预约、内部管理的项目。差异主要集中在接口权限和流量主收益上我整理了一个对照表方便快速判断对比项个人主体企业主体注册成本免费绑定身份证即可需营业执照微信认证需支付300元/年支付能力不支持微信支付支持微信支付、商户号接入类目范围受限部分类目无法选择绝大部分类目可申请流量主/广告部分场景支持全功能支持隐私/合规要求基础配置需要完整隐私协议、类目资质材料我的经验是只要你有一丝可能要做商业项目就注册企业主体哪怕先去办个个体户执照也行成本不高但省掉的麻烦很大。1.2 开发者工具与AppID的真正常见坑注册完成后到设置-开发设置里找到AppID和AppSecret。AppIDwx开头那串是项目身份标识AppSecret是服务端调用接口用的密钥它绝对不能写在代码里甚至不能出现在前端任何请求参数中泄露等于别人可以随意拿你的身份调接口。然后下载微信开发者工具按操作系统装好。新建项目时会让你填AppID也有一个测试号选项可供临时体验但云开发、订阅消息、支付这些能力都必须用真实AppID测试号跑不了完整链路。这个阶段我额外做的一件事是选好基础库版本。不同基础库版本对API的支持不一样在开发者工具的详情-本地设置里可以把调试基础库切成新版但要记住线上用户的基础库版本不一定比你本地新上架前务必在兼容性面板里看一眼项目最低可用版本。工具装好、AppID拿到手先别急着写业务花5分钟把工具里的编辑器主题快捷键方案代理设置调顺手。这些细节很影响日常开发效率。2. 项目骨架与页面配置目录结构搞明白了写页面才能走对地方新建项目后默认生成一个hello world模板很多人直接在这个模板上改改到后面发现乱七八糟。我建议从项目的标准工程结构开始理解再决定怎么组织自己的业务。2.1 目录结构和四个核心文件在管什么事一个典型的小程序项目长这样├── pages/ # 页面目录每个页面一个子文件夹 │ ├── index/ │ │ ├── index.js │ │ ├── index.json │ │ ├── index.wxml │ │ └── index.wxss │ ├── list/ │ └── detail/ ├── components/ # 自定义组件 ├── utils/ # 公共JS工具模块 ├── static/ # 静态图片、图标等资源 ├── app.js # 全局业务逻辑 ├── app.json # 全局配置 ├── app.wxss # 全局样式 └── sitemap.json # 索引配置决定页面是否允许被微信索引每个页面文件夹里的四件套要分清职责.wxml管结构类似HTML.wxss管样式类似CSS.js管逻辑和数据.json管页面级配置比如当前页面的标题、导航栏颜色。新手最容易犯的错是把公共样式写在每个页面的.wxss里结果改一个按钮颜色要动十几个文件这种事遇到一次就会长记性。2.2 app.json的全局配置项逐个说清楚app.json是小程序的总控文件启动时第一个加载的就是它。核心配置项如下pages页面路径数组数组第一项就是小程序启动后的第一个页面。新增页面必须在这里注册否则跳转直接报错。window全局导航栏配置包括navigationBarTitleText标题文字、navigationBarBackgroundColor背景色、navigationStyle设为custom可去掉默认导航栏。tabBar底部Tab配置至少2个最多5个。注意tabBar的页面必须是pages数组里已注册的而且图标文件不能用本地大图建议用80x80以内的png。subpackages分包配置主包不能超过2MB时把低频页面挪到分包。permission涉及定位、相机等敏感接口时这里配置说明文案。这些配置里最高频的坑是页面路径写错工具报module pages/xxx/xxx is not defined这类错基本就是注册遗漏或路径大小写不匹配优先检查这里。2.3 页面生命周期和怎么监听用户离开小程序小程序页面的生命周期顺序是onLoad页面创建→onShow每次显示→onReady首次渲染完成→onHide切后台/跳转→onUnload关闭页面。这是处理数据加载、埋点上报的关键时机。监听用户离开小程序这个问题经常在热搜里出现。它在不同层级有两个解法如果你想知道用户从某个页面切到了微信其他聊天窗口监听页面的onHide就够了如果你想知道整个小程序退到后台需要在app.js里监听App.onHide同时配合onShow做回来时的状态恢复。业务上常见做法是进入页面记录时间戳onHide时算停留时长onShow时恢复计时这样得到的用户活跃数据比在服务端算准确得多。页面间跳转传参也是高频需求简单场景用URL参数navigateTo({ url: /pages/detail/detail?id123 })目标页在onLoad(options)里拿options.id。复杂场景比如需要把整个对象传给下一个页面建议用eventChannel直接拼进URL会又长又容易踩编码坑。3. 数据链路打通登录、请求和列表加载代码的核心都在这页面骨架搭好后下一步就是让数据和后端通信。这一步是整个小程序业务的技术重心也是热搜词里出现最密集的部分包括wx.login()示例、网页端同步登录、列表加载更多一个都跑不掉。3.1 登录流程wx.login拿到的code接下来发生了什么小程序的登录逻辑和传统Web登录不一样它没有密码核心是依赖微信的登录凭证体系。标准流程是// 前端拿到code wx.login({ success: (res) { // res.code 有效期5分钟只能使用一次 wx.request({ url: https://api.example.com/auth/login, data: { code: res.code }, success: (loginRes) { // 后端返回自定义登录态token前端存储 wx.setStorageSync(token, loginRes.data.token); } }); } });code是给后端用的临时凭证后端拿到后调用微信接口code2Session换来openid用户唯一标识和session_key。这里有两个关键原则session_key绝对不能返回前端它涉及敏感用户数据的解密openid也不建议直接对外暴露更好的做法是后端用openid建立自己的用户体系再向下发一个业务token。网页端同步小程序微信登录这个需求很常见比如你有个H5管理后台想用小程序同套账号体系。解决方案是靠微信的UnionID机制小程序、公众号、网站只要绑定在同一个微信开放平台账号下就能拿到同一个UnionID作为统一标识靠UnionID把多端账号串起来。没有绑定开放平台的话各端openid互不相同账号永远合并不了。3.2 请求封装全局拦截器和401续期微信原生的wx.request直接写业务的话代码会非常散。建议在最底层封装一个request函数统一做三件事补全baseURL、带上token、集中处理错误。const request (options) { const token wx.getStorageSync(token); return new Promise((resolve, reject) { wx.request({ url: https://api.example.com options.url, method: options.method || GET, data: options.data || {}, header: { Authorization: Bearer token }, success: (res) { if (res.statusCode 401) { // token过期走刷新或重新登录逻辑 handleTokenExpired(); return; } if (res.statusCode 200 res.statusCode 300) { resolve(res.data); } else { wx.showToast({ title: 请求失败, icon: none }); reject(res); } }, fail: (err) reject(err) }); }); };注意onReachBottom触发加载更多时如果请求还没回来用户又滑到底部会重复发请求。行业内通用做法是加一个loading布尔锁请求发出后置true响应回来后置false在回调里判断锁状态决定是否请求下一页。3.3 列表页的加载更多和下拉刷新到底怎么写热搜里页面列表加载更多几乎天天有人问。它的标准实现分三步在data里维护page、pageSize、list、hasMore四个字段。页面滚动到底时onReachBottom触发此时把page加一按新页码请求接口把返回数据concat到原list。每次请求前先判断hasMore服务端返回数据条数小于pageSize时把hasMore置false。下拉刷新则需要两处配合页面的.json里开启enablePullDownRefresh然后重写onPullDownRefresh方法把page重置为1、清空list、重新请求最后记得调用wx.stopPullDownRefresh()收起加载动画新手最容易忘记这一步导致刷新动画一直转。分页接口返回的字段建议统一定义为{ list: [], hasMore: true }这样所有列表页共用一套分页逻辑不用每个页面单独判断。3.4 顶部导航栏高度适配和搜索框聚焦偏移顶部导航栏高度这个问题本质上是在做自定义导航栏或键盘弹起适配时出现的。微信的导航栏由状态栏顶部显示时间电量的区域和标题栏两部分组成状态栏高度可以用wx.getSystemInfoSync().statusBarHeight拿到而标题栏高度不是固定值不同机型有差异。正确做法是用wx.getMenuButtonBoundingClientRect()拿到右上角胶囊按钮的位置信息包括它的宽高和顶部距离导航栏总高度约等于statusBarHeight 胶囊高度 胶囊上下间距。网上流传的固定44像素写法在iPhone X系列的刘海屏上必出问题。至于移动搜索框聚焦后会偏移我排查下来多数是两个原因一是搜索框用了position: fixed定位键盘弹起时页面被压缩fixed元素相对视口的位置错乱二是cursor-spacing设置不当输入框被键盘遮挡后页面自动滚动导致视觉偏移。建议给input设置cursor-spacing为15到20并且监听bindfocus事件时手动wx.pageScrollTo滚动到搜索框位置实测能解决九成偏移问题。4. 常用能力集成与真机兼容的坑订阅消息、录音格式、特殊API一次说清业务功能做多了就会发现小程序的坑不在纯页面开发而在于各种开放能力与真机环境的适配。下面这几个点都是我实际踩过、且经常出现在热搜里的。4.1 订阅消息授权一次性订阅如何变多次提醒很多运营想要用户每天都能收到通知误以为订阅一次就够了。微信订阅消息的规则是用户每次授权只允许给你发一条模板消息如果想长期发送得选择长期订阅但长期订阅只对特定行业开放绝大多数普通小程序只能走一次性订阅。所以在设计交互时要注意别在用户刚进页面时就弹授权框那样授权率很低且体验极差。常见做法是让用户主动点击某个按钮比如开启提醒后再触发wx.requestSubscribeMessage这样弹框出现有用户主动意图做铺垫授权率明显高。再进阶一点的做法是把需要提醒的场景拆成多个模板比如预约成功提醒开始前提醒结果通知每个模板各订阅一次变相实现多次触达。4.2 模拟器与真机的差异录音格式只是个开始模拟器的录音API生成的录音文件是什么格式这个问题我印象很深。微信小程序的RecorderManager在真机上会生成可播放的音频文件常见格式是aac或mp3但在开发者工具的模拟器里录音能力是用电脑麦克风实现的输出文件的编码格式可能和真机不一致甚至某些场景下录出来无法在真机正常播放。这类问题不是个例凡是和硬件相关的能力模拟器和真机的表现都可能不同。举例来说live-player的全屏按钮在PC版开发者工具上经常点击没反应但真机正常iOS防截屏用wx.setVisualEffectOnCapture模拟器上完全看不出效果只有真机生效。这类模拟器正常、真机翻车的问题没有捷径唯一的可靠经验就是涉及硬件与系统能力的功能一定要拉真机验证别在模拟器上自我感动。4.3 蓝牙定位、柱状图、视频下载这类扩展能力速览点击热搜词会发现开发者们最常问的扩展能力还有这么几类蓝牙定位室内定位和硬件设备通信场景常见核心API是wx.openBluetoothAdapter和wx.startBluetoothDevicesDiscovery真机上需要开启蓝牙权限iOS还需要额外处理系统权限描述。柱状图小程序没有内置图表组件主流方案是集成ec-canvas画图其实质是把ECharts的核心库压缩后在小程序Canvas上渲染。用的时候注意每个图表单独引入组件别全局引入导致包体积爆炸。视频下载先wx.downloadFile下载到临时文件再wx.saveVideoToPhotosAlbum保存到相册保存前需要用户授权scope.writePhotosAlbum用户在设置里关掉授权后需要引导去设置页重新打开。天地图/地图集成第三方地图服务时记得在公众平台后台配置request合法域名官方地图API能用的业务场景尽量优先用官方的。这些能力的关键点都在于先用官方文档确认API在当前基础库的可用性再动手写很多接口要设置权限配置或者功能页申请比写代码本身更容易卡人。4.4 高频报错排查10002错误和包体积超限微信小程序10002这个错误经常出现在热搜它属于系统级错误码文档一般只写系统错误实际排查时十有八九不是系统问题。我的处理套路是先定位是哪个接口触发的再看请求参数是否符合预期尤其检查登录态是否失效、必传参数是否为空。这类错误在请求封装层统一打日志是最快的排查方式否则等到线上出问题再临时加日志成本很高。另一个高频问题是source size 2612kb exceed max limit 2mb即主包超过2MB无法上传。解决方案按优先级排列把不常用页面拆分到subpackages分包里。图片资源全部替换为CDN链接本地只留启动图和必要图标。检查是否有重复引入的第三方库比如同一个工具函数被多个页面重复拷贝。使用开发者工具自带的代码依赖分析面板直观看哪个文件占了大头。分包是最有效的根治手段微信小程序主包2MB、总包和分包合计20MB的限制绝大多数业务靠合理分包都能塞下。5. 调试与抓包比console.log更高效的线上排错手段开发完功能真正花时间的往往是调试。很多问题在开发者工具里复现不了或者报了错但看不到真实数据这时候就需要一套调试打法。5.1 自带的调试面板和vConsole够用了微信开发者工具自带的Debugger面板覆盖了Console、Network、AppData、Storage、Wxml等维度。页面渲染有问题先看Wxml面板请求没通先看Network面板数据不对先看AppData和Storage。真机预览时手机上显示不了Console日志但可以在真机上开启vConsole。方法有两种在app.js里执行wx.setEnableDebug({ enableDebug: true })或者通过微信的调试菜单入口打开。开启后手机上会出现一个绿色小圆点点开就是完整的日志、网络、存储面板。注意vConsole在生产环境要关掉否则暴露内部日志给用户既有安全风险也消耗性能。5.2 用charles抓包小程序请求的实战场景微信开发者工具自带的Network面板能看请求但它只覆盖工具内部模拟器发出的网络请求。真机上的某些请求尤其是第三方SDK发出的、或需要查看完整请求头/响应体的场景Network面板就不够用了。这时候我习惯用Charles这类抓包调试工具来看。基本配置思路不复杂电脑和手机连同一个局域网在Charles上开启SSL Proxying手机安装对应调试证书后小程序的HTTPS请求就能在Charles里看清真实报文。我能看到请求的完整头信息、登录token是否带上、服务端返回原始JSON定位问题比在代码里猜快得多。用到的场景一般是后端说我这边没问题啊你来抓包看真实返回值或者排查某个请求为什么在真机上超时、在模拟器上正常。这里要提醒一句抓包工具只用来调试自己开发的小程序的后端接口请勿用于任何非授权的流量分析场景。5.3 真机调试的完整链路和怎么发给别人试用要把开发中的项目发给其他人试用收集反馈不能直接扫码预览就完事。预览二维码的有效期只有几分钟而且预览者必须是你账号下的开发者或体验成员。正确的分发流程是在开发者工具点击上传填写版本号和备注代码进入公众平台后台。在后台版本管理-开发版本里找到刚上传的版本点击选为体验版。在成员管理里添加体验成员微信号或生成体验版二维码发给对方。对方扫码后就能打开正式包体验这个二维码长期有效你不用守在电脑旁边。体验版和正式版走的是同一套生产代码只是没有过审核所以非常适合做内测和反馈收集。我一般会在每次迭代后出一版体验版给客户收集一轮反馈再提审这样能避免审核通过之后才发现重大需求偏差。6. 从开发完成到最终上线提交审核、类目合规与多端打包的最后一公里功能写完、内测通过不等于事情结束。上架审核这一环很多开发者第一次走会卡半个月原因集中在类目选择不当、隐私协议缺失、资质材料不全。6.1 发布流程上传、提审、发布三步走在开发者工具点上传后到微信公众平台后台的版本管理里能看到刚上传的开发版本。提审之前按官方要求先把用户隐私保护指引配置好涉及收集用户信息的逐项声明用途没有配置隐私指引的版本基本会被直接驳回。提交审核时填写的功能页面描述要准确比如你做了个点餐系统核心路径就是选店-下单-支付把这个功能路径写清楚审核会快很多。审核通过后不会自动上线需要手动点击发布才算真正面向用户。一般我的节奏是周一上午提审审核周期大约1到7天过了第一次审核后后续更新因为有了历史记录通常会更快。6.2 类目选择和特殊协议AI类目、三方合作类的处理热搜里有人问添加AI类目跟第三方的合作协议要怎么签这个问题涉及的是类目选择。类目选得不合适审核人员会退回让你补充资质。AI对话类的产品通常需要选择工具-信息查询等对应类目如果服务涉及第三方大模型能力需要准备和第三方的合作协议或者授权说明明确数据来源和调用权限。每家小程序主体资质不同最稳妥的方式是先在后台类目管理里查看你选的类目要求的资质材料清单按清单准备缺什么补什么别自己猜。6.3 uniapp打包小程序的体积控制与跨端注意事项现在很多项目用uniapp开发一套代码同时出小程序和App。uniapp跑小程序时的核心坑是包体积它的运行时代码本身就有几百KB业务代码稍微上点量就触发2MB限制。热搜里的source size 2612kb就是这么来的。处理手段和原生小程序一样分包、压缩、外链资源。uniapp里还可以开启分包优化在manifest.json里配置optimization相关选项。另外要注意uniapp用的一些vue生态组件在小程序端并不兼容比如直接操作DOM的库在模拟器上可能能跑但真机上白屏跨端项目里尽量用官方推荐的兼容组件。如果你是从小程序迁移到uniapp或者反方向迁移最费精力的不是页面重写而是各种微信特有API的封装差异建议提前抽一层平台判断工具把wx.xxx的调用统一包起来。做了这么多项目下来我最大的感受是微信小程序的开发流程本身没什么玄学难点在于把每个环节的经验串成链条——选主体时多想一步将来要不要支付写布局时多想一步真机兼容调接口时多想一步token过期传包时多想一步分包策略。流程跑顺了后面接什么业务都快。如果你正准备做第一个小程序别追求一步到位先把这个流程完整走一遍哪怕做个最简单的工具页很多困惑会在动手之后自己消失。