先说结论用微信原生框架从零开始写一个能正常上线的小程序没有想象中那么玄乎但也不会像看几分钟视频就能马上搞定那么容易。这篇文章我想用一个名字叫 WorkBuddy 的“工作辅助小程序”当例子把从注册账号、安装开发者工具、创建第一个页面、接上云数据库到最后上传代码、提审上线的完整流程一五一十讲清楚。不管你是刚接触小程序开发还是之前只用网页或者脚本写过一些工具只要愿意动手跟着做基本上都能把一个能用的版本跑起来而且做完之后心里的整个链路会清晰很多。WorkBuddy 这个名字没什么花头就是 Work干活 Buddy搭档。它的定位是一个帮上班族或自由职业者打理日常任务的工作台列待办、记工时、做简单的工作复盘。这类工具很适合当第一个小程序项目因为功能直观、数据模型简单但又覆盖了小程序开发最核心的几条赛道页面结构、列表渲染、事件交互、数据存储、发布流程。跟着做一遍相当于把一段完整的产品闭环走了一遍。下文里我会尽量按照实际操作顺序来讲遇到关键步骤会解释为什么这么做而不是只让你复制粘贴。1. 动手之前WorkBuddy 要做成什么先想清楚再动手很多新手拿到小程序项目就急着写代码这是最大的坑。我先展开说说 WorkBuddy 的功能边界和整体技术选型这两件事决定了后面写代码的时候会不会反复返工。1.1 功能定型和范围控制MVP 怎么切分WorkBuddy 面向的是日常工作场景如果一开始就把什么日历、周报、多人协作、消息提醒全塞进去那估计一个月都开发不完。做第一版的时候我建议只保留三个核心模块待办管理能新增待办事项、标记完成、删除已完成事项工作记录记录当天的工作任务和实际耗时简单做一条一列的数据数据看板统计今日完成数量、待办总数、累计工时用一个页面展示这个范围看起来小但它已经能用“真实的业务逻辑”把整个小程序串起来首页是待办列表第二个页面是工作记录的填写和列表第三个页面是数据和设置。三个页面之间的数据流是一致的不存在逻辑冲突非常适合当一个全流程范例。如果后面想扩展比如加登录体系、加多人共享清单也都是在现有数据模型上加字段不会推倒重来。我还想强调一个原则第一版不要碰支付不要碰客服消息不要碰用户身份绑定这些“看起来不难但实际很重”的能力。小程序里有些能力是“能用”和“能上线”两回事比如用户隐私相关接口审核的时候要求非常多。WorkBuddy 第一版就把所有数据存储放在本地缓存和云开发数据库不上任何实名认证体验链路完整门槛也低。1.2 技术选型为什么选原生框架加云开发小程序开发有几种常见路线微信原生框架、第三方跨端框架如 Taro、uni-app、纯 Web 套壳。我的建议是如果以“学会小程序开发底层逻辑”为目标必须以微信原生框架为主。原因很简单原生框架的 WXML、WXSS、JS、JSON 四件套是官方定义的所有功能官方文档都有对应说明出了问题社区也比较容易搜到。第三方跨端框架虽然一套代码能同时出小程序和 App但它多了一层编译转换遇到边界问题排查成本反而更高。WorkBuddy 这个项目没有多端需求用原生最直接。后端部分我选了微信云开发。这个决定主要是想省掉一台服务器和域名备案的麻烦。云开发提供云数据库、云函数、云存储对小程序项目来说等于在微信的体系内直接拿到了一个后端底座。开发者不需要自己购买云主机、配置 Nginx、搭 HTTPS 证书也不需要处理跨域因为云开发和小程序之间天然联通。对小项目来说云开发还提供有免费额度WorkBuddy 这种量级的个人工具基本够用。就算以后用户量大了再平滑去接自己的后端服务也不冲突因为业务逻辑都在前端替换起来只是改数据请求层而已。2. 环境准备三件套账号、开发者工具、项目初始化这一节属于纯粹的“磨刀不误砍柴工”。很多人会在这一步卡住大部分问题是注册信息对不上、工具版本选错、项目模板误选。我按顺序拆开讲。2.1 注册小程序账号并拿到 AppID打开微信公众平台点击右上角的“立即注册”选择“小程序”类型。这里有个细节如果你已经有微信公众号账号不建议用公众号里的“小程序”入口直接创建因为主体关联复杂个人开发时非常容易把管理员信息绑定错。最好重新用邮箱注册一个小程序账号。注册流程按系统提示走就行重点注意几个信息邮箱必须没注册过公众号或小程序主体类型建议先选“个人”审核流程简单、不用对公账户打款验证平台会要求绑定管理员微信这个管理员就是以后唯一能扫码登录后台的人别随便绑注册完成后进入小程序后台在“开发管理”的“开发设置”里能看到一串 AppID形如wx1234567890abcdef。这串东西相当于小程序在微信体系里的身份证后面创建项目必须用到。注意还有一个叫“AppSecret”的东西它主要给服务端 API 调用用前端代码里永远不要写 AppSecret否则等于把整个后台钥匙直接暴露出去。2.2 安装开发者工具并创建第一个空白项目微信开发者工具是日常开发的入口直接在官网下载稳定版即可。安装的时候有个小建议Windows 系统尽量选默认安装路径因为工具内置了一些调试相关组件路径有中文或者空格偶尔会触发无法解释的报错。打开工具用管理员微信扫码登录。然后选择“小程序项目”项目名称填 WorkBuddy目录选一个专门放代码的文件夹AppID 就填刚才注册拿到的那个后端服务选“不使用云服务”或者“使用云开发”都可以因为即使现在选“不使用”后边也能手动开通。模板那里关键一步不要选任何现成模板直接选“不使用模板”或者“空白目录”。创建完成后你会看到一个满屏的欢迎页和一堆文件。很多人第一次会懵我先讲一下原生小程序的标准目录结构这在后面写代码时会反复使用app.js小程序逻辑入口注册应用实例适合放全局数据和生命周期方法app.json全局配置包括页面路径、窗口样式、导航栏、TabBarapp.wxss全局样式所有页面都会继承这份样式pages/目录每个页面一个文件夹里面包含.wxml、.wxss、.js、.json四个同名文件project.config.json项目配置记录 AppID 和工具设置WorkBuddy 我准备做三个页面在pages/index待办主页、pages/task工作记录页、pages/profile数据看板与设置页之间切换。新建页面的方式有两种一种是在pages目录右键新建 Page工具会自动生成四个文件另一种是在app.json的pages字段里手动加一行路径后保存工具也会自动补齐文件。第二种更贴近实际开发节奏后边我讲配置时会用到。注意小程序里app.json的pages数组第一项就是启动页WorkBuddy 的首页必须写在第一行否则每次启动可能落在别的页面。3. 从空白目录到工作台页面全局配置和首页交互环境搭好之后真正的开发流程开始了。这一节先解决“项目长什么样”和“首页怎么交互”这两个问题代码不多但要把逻辑理顺。3.1 全局配置导航条、TabBar 和页面注册打开app.json这是一个 JSON 文件里面的字段直接决定小程序壳子的行为。WorkBuddy 有三个 Tab 页面所以底下需要一个 TabBar让用户能一键切换。我给出一份可以直接用的配置{ pages: [ pages/index/index, pages/task/task, pages/profile/profile ], window: { backgroundTextStyle: light, navigationBarBackgroundColor: #2F54EB, navigationBarTitleText: WorkBuddy 工作台, navigationBarTextStyle: white }, tabBar: { color: #999999, selectedColor: #2F54EB, backgroundColor: #ffffff, borderStyle: black, list: [ { pagePath: pages/index/index, text: 待办 }, { pagePath: pages/task/task, text: 记录 }, { pagePath: pages/profile/profile, text: 我的 } ] } }这段配置里的小细节挺多。pages数组里的路径不能写.wxml后缀只写页面目录名。tabBar.list最少 2 项、最多 5 项顺序决定了显示顺序。TabBar 也可以配iconPath和selectedIconPath但图片素材这版本可以不加因为如果图标没有及时准备工具会直接报编译错误。用纯文字 TabBar 不影响正常使用等以后设计稿出来再补图标就行。导航栏标题色和背景色我用了一套偏商务的蓝这个大家按自己喜好定但注意navigationBarTextStyle只有white和black两个值浅色背景必须配black深色背景配white否则字会看不清。保存之后工具会自动编译左侧模拟器里会出现一个带三个 Tab 的小程序外壳。如果页面对应目录还没生成文件工具会在控制台提示找不到页面所以接下来要顺手把三个空页面建出来。我习惯先在app.json里写好路径再保存让工具自动生成文件这样连新建 Page 那步都省了。3.2 首页待办列表数据绑定、事件处理和输入框首页是 WorkBuddy 的门面用来列待办事项。一个待办项最简单的数据结构只需要三个字段id、title、done。id用来标记唯一身份title是任务描述done是个布尔值表示是否已完成。首页功能我给三个添加任务、勾选完成/取消、删除已完成任务。先看pages/index/index.wxml这里用wx:for实现列表渲染每行渲染一条待办view classpage view classinput-row input placeholder输入待办事项 value{{inputValue}} bindinputonInput confirm-typedone bindconfirmaddTodo / button sizemini typeprimary bindtapaddTodo添加/button /view view classtodo-list view wx:for{{todos}} wx:keyid classtodo-item {{item.done ? done : }} checkbox checked{{item.done}}>Page({ data: { todos: [], inputValue: }, onInput(e) { this.setData({ inputValue: e.detail.value }); }, addTodo() { const title this.data.inputValue.trim(); if (!title) { wx.showToast({ title: 内容不能为空, icon: none }); return; } const todos this.data.todos.concat({ id: Date.now(), title: title, done: false }); this.setData({ todos, inputValue: }); }, toggleTodo(e) { const index e.currentTarget.dataset.index; const todos this.data.todos; todos[index].done !todos[index].done; this.setData({ todos }); }, deleteTodo(e) { const index e.currentTarget.dataset.index; const todos this.data.todos; todos.splice(index, 1); this.setData({ todos }); } });这里有一个新手高频踩坑点在小程序里直接修改this.data.todos[index]后再调用this.setData({ todos })是可以生效的但在更复杂的数据结构里容易出问题因为setData的对比过程不一定能正确识别深层变化。更稳的做法是复制一份新数组再操作const todos [...this.data.todos]; todos.splice(index, 1); this.setData({ todos });用这个写法每步操作都在新数组上完成避免踩到setData对深层数据监听不一致的坑。另外wx:for的每一项一定要有wx:key并且key必须是项目里唯一且稳定的值这里用的id正好符合。如果不写wx:key控制台会有警告如果这个列表未来会支持拖拽排序或复杂更新没有稳定key甚至会导致渲染错乱。4. 把数据留住本地缓存到云开发数据库首页现在能用但一关掉小程序数据全没了因为数据只存在内存里。这一节解决数据持久化的问题。我先说本地缓存因为对一个小工具而言本地缓存是最快、最稳定、零成本的方式然后再引出云开发这样数据能跨设备同步也为以后多端使用留好能力。4.1 本地缓存用 Storage 保住新增和修改微信小程序提供了wx.setStorageSync和wx.getStorageSync两组接口用于同步读写本地缓存。这两组接口底层就是 Key-Value 存储容量上限单条 1MBWorkBuddy 的待办列表和记录列表完全够用。用法特别简单在addTodo、toggleTodo、deleteTodo三个方法里分别加上一行wx.setStorageSync(todos, todos);然后在页面的onLoad生命周期里读取缓存并初始化onLoad() { const todos wx.getStorageSync(todos) || []; this.setData({ todos }); }这里有一点非常关键onLoad只在页面第一次加载时执行一次后续如果从别的页面跳转回来不会再执行。WorkBuddy 的 Tab 页面默认是留在内存里的从“记录”切回“待办”时不会触发onLoad。所以如果数据在“记录”页被改动了回“待办”页时要保证数据最新通常的做法是在onShow里重新拉取缓存onShow() { const todos wx.getStorageSync(todos) || []; this.setData({ todos }); }用onShow的好处是每次页面重新显示都会执行这样能保证页面间的数据同步。逻辑上等于每次切回首页都“刷新一次”这个小细节能让用户体验明显提升。4.2 云开发集合设计、数据库权限与云函数本地缓存够用但不支持多设备同步也不方便以后做数据分析。所以 WorkBuddy 第二版开始接云开发这一步能学到的知识也更接近真实商业项目。在开发者工具里点击“云开发”按钮开通环境。这里的“环境”相当于一个独立的隔离环境每个环境里有自己的数据库、存储和云函数。开发环境和生产环境最好分开但 WorkBuddy 第一版只开一个环境就够了毕竟核心是跑通流程。云开发数据库是一种文档型数据库类似 MongoDB 的用法。数据以“集合”为单位组织WorkBuddy 只需要建一个集合名字叫todos。每个待办记录就是集合里的一条文档文档可以理解成一个 JSON 对象。我设计的待办文档结构是{ _id: 自动生成, title: 整理项目周报, done: false, createTime: 1700000000000, updateTime: 1700000000000 }_id是文档唯一标识不需要自己传插入数据时后端会自动生成。createTime和updateTime我建议主动写入因为后面做统计排序时一定要用到时间字段。如果不在写入时存时间后面就没有任何方式可以找回“这条任务是什么时候创建的”这一点经常被漏掉。数据库权限这里要特别小心。在云开发控制台里每个集合的权限默认是“仅创建者可读写”如果想做到“用户不需要登录也能在全网数据里读写”这不是一步改权限就能解决的。WorkBuddy 第一版没有做登录体系最省事的做法是让前端直接用wx.cloud.database()操作集合但这要求数据权限设置为“所有用户可读仅创建者可读写”之类的宽泛规则。安全上更稳妥的做法是通过云函数来操作数据库这样前端不直接暴露数据库读写权限。虽然 WorkBuddy 的演示属性比较强但我还是强烈建议走云函数这条路因为实际项目里这是主流做法也能避免将来上线后被扫描接口薅数据。云函数本质是一个运行在云端的 Node.js 函数。在开发者工具里右键cloudfunctions目录新建云函数名字叫addTodo然后修改入口文件index.jsconst cloud require(wx-server-sdk); cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }); const db cloud.database(); exports.main async (event) { const { title } event; if (!title) return { code: 1, msg: 缺少title }; const res await db.collection(todos).add({ data: { title, done: false, createTime: Date.now(), updateTime: Date.now() } }); return { code: 0, data: res._id }; };然后在每个云函数目录上右键选择“上传并部署云端安装依赖”云函数才能在小程序里被调用。前端调用云函数的代码wx.cloud.callFunction({ name: addTodo, data: { title }, success: (res) { console.log(新增结果, res.result); } });加了云函数之后前端代码量会多一点但数据安全性和架构清晰度都上来了。WorkBuddy 的架构最后变成这样前端页面展示状态 → 事件触发 → 调用云函数 → 云函数访问云数据库 → 返回结果 → 前端重新拉取列表。链路虽然比本地缓存长但每一步都看得懂出了问题就能单独排查。5. 记录页和统计页把多个页面串成完整闭环首页解决完待办列表WorkBuddy 还需要一个“工作记录”页面和一个“数据看板”页面这才像一个工具型小程序。5.1 工作记录页表单输入和记录列表工作记录页用来提交“今天做了什么事花了多少时间”。操作流程是用户输入工作描述、选择耗时分钟数、点击保存记录会出现在下方的历史记录列表里。表单页用.wxml写两个控件一个输入框一个 slider 滑块view classpage view classform-card view classfield-label工作内容/view input placeholder例如整理需求文档 value{{workDesc}} bindinputonDescInput / view classfield-label耗时{{minutes}} 分钟/view slider min5 max120 step5 value{{minutes}} bindchangeonMinutesChange show-value / button typeprimary bindtapsaveRecord保存记录/button /view view classrecord-list view wx:for{{records}} wx:keyid classrecord-item text{{item.desc}}/text text{{item.minutes}} 分钟/text /view /view /view页面数据里维护workDesc、minutes、records三个字段。保存的时候构造一条新记录追加到records数组同时写入缓存。和首页待办的处理方式一致最好把读写逻辑抽出一个通用的数据服务层不让每个页面都直接拼wx.getStorageSync。虽然 WorkBuddy 的代码量还不算大但有了数据层之后页面代码会干净很多后面接云开发也只需要改数据层一个文件。这个习惯越早形成越有益。工作记录页还有一个可加可不加的能力每天第一次打开时自动显示当前日期作为记录的分类维度。实现不难在onShow里取一下系统时间并格式化即可。不要小看这个“日期”字段后续统计“今天完成多少”“本周工时”都依赖它没有日期数据看板根本无从做起。5.2 数据看板统计和展示本地数据“我的”页面要承担两个职责展示今日完成情况和提供基础设置入口。WorkBuddy 的统计逻辑可以做成待办总数todos.length已完成数量todos.filter(item item.done).length今日新增记录数量按createTime筛选当天的记录数今日投入总分钟数按日期筛选后累加minutes这些统计在数据量比较小的时候直接在前端用 JavaScript 的filter和reduce计算就行不需要数据库做聚合查询。比如今天的完成数const now new Date(); const todayStart new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime(); const todayEnd todayStart 24 * 60 * 60 * 1000; const todayRecords records.filter(item { return item.createTime todayStart item.createTime todayEnd; }); const totalMinutes todayRecords.reduce((sum, item) sum item.minutes, 0);这里有个时间戳细节Date.now()返回的是毫秒级时间戳而24 * 60 * 60 * 1000是一天的毫秒数。很多新手在统计“当天”数据时会把起始边界算错导致统计结果看起来少了一天。调试方法也很简单把开始和结束时间戳console.log出来放进时间戳转换工具里确认边界基本能避免这类问题。数据看板的展示形式不建议搞复杂的图表小程序里画图表需要额外引用第三方库对项目体积和调试都有影响。直接用数字卡片排列展示就好简洁、加载快也不容易出兼容性问题。第一版的目标永远是先把核心流程跑通而不是引入一堆华丽但在当前阶段用不上的依赖。6. 模拟器调试到真机发布从关卡到真正上线代码写到这里WorkBuddy 的核心功能已经完整了。接下来这个阶段是很多教程一笔带过但其实最容易翻车的部分怎么从“能跑”到“能上线”。这里面的坑多为环境问题、权限问题和编译缓存问题。6.1 模拟器调试必须盯住的几个检查点我把.wxml、.wxss、.js、.json四类文件在调试时的重点分开来说因为对应到不同的问题排查思路。.wxml文件里最常见的问题就是路径写错、组件名拼写错误、数据绑定字段名大小写不一致。开发者工具的调试器里有一个“WXML”面板点它可以看到页面的真实渲染树。如果页面空白但控制台没有报错优先打开 WXML 面板看看是不是wx:if把整个内容拦掉了。.wxss文件要注意小程序里默认的单位是rpx不是px。rpx是响应式像素以屏幕宽度 750 为基准来换算能自动适配不同宽度的手机。如果拿网页开发的px习惯直接写死在 iPhone 全面屏和安卓手机之间会出现明显的布局错位。WorkBuddy 里按钮高度、列表内边距这些地方我全部用rpx只在边框粗细这种必须精确的地方用px。.js文件的调试主要集中在数据变化是否符合预期。模拟器里选中某个页面组件可以在 Console 里通过getApp()拿到全局对象配合打印this.data可以实时观察数据状态。如果你的页面数据更新了但视图没变第一反应检查setData的 key 路径确认没有在对象里新增了未初始化的字段。.json文件配置的坑多数在页面级配置覆盖全局配置时。比如navigationBarTitleText在全局已经设置了“WorkBuddy 工作台”但在某个页面的.json里又写了别的标题那这个页面上的标题就会局部覆盖全局值。这类问题在视觉上很明显但新手容易以为是 bug其实是优先级规则在起作用。6.2 真机预览、体验版和提审上线模拟器上一切正常和真机上正常是两码事。模拟器在开发者工具里渲染方式和微信客户端内实际渲染逻辑有细微差别尤其是输入框、滑块这些原生组件。所以无论如何都要养成的习惯是每个里程碑节点都做一次真机预览。点击工具栏里的“预览”按钮会生成一个临时预览二维码。用微信扫码后就能在手机微信里打开当前代码的小程序。真机预览有一个限制临时二维码只对当前开发者微信有效有效期大约 25 分钟只适合自己调试不适合发给别人测试。要让别人也能体验需要把代码上传。在工具右上角点击“上传”填好版本号和备注版本号按0.1.0这种语义化方式去写。回到小程序后台的“版本管理”会看到刚才上传的版本。点击“设为体验版”再把体验版二维码发给同事或朋友他们就能以“体验成员”身份使用这个版本。注意体验成员需要我们提前在后台“成员管理”里添加微信号这一步经常被忽略导致别人扫码后显示无权限其实就是没把对方加到体验成员列表。最后一步是提审上线。在版本管理里选择体验版本点击“提交审核”。提交时要选择类目WorkBuddy 属于“工具-效率”选一个符合的类目即可。审核通常需要一两天期间别闲着可以顺手准备一下应用截图和隐私说明。特别是涉及到收集用户录入的内容即使只是文字现在平台要求补充隐私保护指引需要在后台的“设置-用户隐私保护指引”里填写否则审核会被驳回。我第一次提交这类工具小程序时就因为漏了隐私指引被驳回过一次驳回原因写得很清楚按提示补上基本上都能过。关键经验审核驳回不可怕怕的是反复提交不检查。每次驳回通知里都把违规原因和需要修改的点列得很清楚严格按照提示修完、上传新版本再走一遍提交审核即可。7. 开发中必踩的坑WorkBuddy 高频问题清单这些问题是基于实际开发中高频出现的问题我整理成一个速查表方便大家对照自查现象可能原因解决办法页面打开是白屏app.json中页面路径错误或大小写不对检查路径是否精确匹配pages目录结构删除缓存后重新编译控制台提示wx:for警告遍历时没有指定wx:key补充wx:keyid且确保id唯一稳定样式不生效或布局错位混用px和rpx导致适配问题按小程序规范统一用rpx边框等精确尺寸用px数据存储正常但重启后丢失只写入了内存没有写入缓存在修改数据后调用wx.setStorageSync落盘在某个页面改了数据另一个页面没更新Tab 页切换不触发onLoad将数据同步逻辑放在onShow里云函数调用失败云函数未上传或环境不一致确认云函数目录已右键上传检查环境 ID 是否匹配真机预览正常但审核被驳回隐私保护指引未填写或类目不匹配在后台检查隐私指引、服务类目按要求补充说明setData后视图不变化深层对象属性被直接修改未触发更新复制新对象后再setData以上每一条都是实际开发中会反复碰到的场景WorkBuddy 从零到能拿到体验版至少会踩到其中三四条。提前把这些问题理清楚后面遇到时就不会浪费时间瞎折腾。8. 项目还能怎么扩展从 WorkBuddy 到你自己的产品WorkBuddy 做完之后它不是终点而是一个可扩展的起点。很多开发者第一次完成项目后会在心里产生“我这是不是太简单了”的疑问。我的看法是只要它完整走完了从注册到发布的全链路且没有明显逻辑错误这个项目就已经具备了继续迭代的基础。最容易加的扩展点是用户体系。接入微信的wx.login拿到用户的唯一标识然后把它作为每条待办、每条记录的ownerId。这样不同用户登录后看到的就是自己的数据多人数据不会互相污染。在云开发里这一步已经比较成熟本质上就是在查询条件里加上openid过滤不需要额外引入大型后端框架。另一个有意思的扩展方向是给数据增加“标签”能力。比如 WorkBuddy 里记录的工作项可以打上“开会”“写代码”“沟通”这些标签然后统计页按标签维度展示工时分布。数据模型上只是多一个tags数组字段页面里加一个标签选择器画布上如果要用图表可以引入小程序版的图表库不过记得控制包体大小。第三个方向是和微信消息订阅能力结合做一个“每日提醒”。用户订阅了待办提醒后云函数定时触发通过订阅消息推送给用户。这个能力对工具类小程序有显著加持效果但会涉及用户授权和消息模板配置复杂度比前一节的功能上了一个台阶。等 WorkBuddy 的本地流程已经玩熟再考虑这块即可。WorkBuddy 这个项目规模不大但五脏俱全有页面交互、有本地数据、有云端能力、有完整的发布链路。拿它练完手再去研究商业级小程序的框架设计、组件封装、自动部署这些高级话题就会觉得基础没有白费。如果你想做一个自己的小工具照着这条从 0 到 1 的路重新走一遍很快就能跑出第一个可以给别人用的版本。