做微信小程序这件事，我前后拖了快两年。网页版的2048小游戏早写好了，朋友一直说“包一层壳就能上微信”，真动手才发现完全不是那么回事——小程序的运行机制、发布审核、登录授权，每一环都跟网页开发隔着一条河。最近总算用WorkBuddy把这个工程从网页重构成了小程序，从生成代码到提交审核，前后花了一个周末。如果你也打算用AI工具做微信小程序，这篇应该能帮你少踩几个坑，至少不用像我一样在“为什么手机号授权不弹窗”这种问题上耗掉半天。
先说结论：AI工具写小程序，难点根本不在“写代码”，而在“平台上下文”。WorkBuddy这类带工作台概念的工具，比我之前用过的通用AI助手强在它能理解微信小程序这个特定场景——知道WXML不是HTML，知道app.json是干嘛的，知道wx.login和getPhoneNumber该怎么用。这篇就把我用WorkBuddy从零搭一个小程序并跑通上线全流程的实操过程拆开讲，顺带把上线前那些容易卡住的细节都捋一遍。
1. 为什么我用 WorkBuddy 而不直接手写或找通用AI帮手
1.1 小程序开发，和普通网页开发从根上就不一样
很多人以为小程序就是“把网页塞进微信里”，这是最大的误区。微信小程序虽然表面上是前端技术，但架构上跟传统网页几乎完全不同。
网页跑在浏览器里，DOM是开放的，你想怎么操作就怎么操作。小程序是双线程模型：逻辑层跑在JavaScript引擎里，渲染层跑在WebView里，两层之间靠setData通信。意味着你不能直接操作DOM，不能随便用window、document那一套浏览器API，也不能用jQuery这类依赖DOM的库。我最初把网页版2048直接丢进小程序开发者工具，白屏，控制台报了一堆“wx is not defined”“document is not defined”的错误——这就是不了解架构差异的代价。
还有样式。小程序用WXSS，虽然有rpx这种适配单位很好用，但选择器支持有限，不支持通配符*，不支持很多伪类。写惯了CSS的人上手WXSS，容易在“为什么这个样式没生效”上怀疑人生。我周围不少朋友第一个小程序项目死在“写完代码跑不起来”这个阶段，其实大概率就是被这套隐性规则绊住了。
1.2 WorkBuddy 解决的是“平台上下文”问题
用通用AI写小程序代码，经常遇到一种尴尬：它生成的代码语法完全正确，但用在微信环境里就是不行。比如它可能生成document.getElementById来操作节点，可能用localStorage而不是wx.setStorageSync，甚至可能用ES6模块的原生import而不做构建处理。代码本身没错，错在“不懂微信的规矩”。
WorkBuddy不一样的地方在于，它天然带工作台和项目上下文概念。我不用每次对话都重复说“这是微信小程序项目，请使用WXML/WXSS，图标用iconfont，数据存储用wx.setStorageSync”——你只要把项目结构在工作台里搭好，它就知道在什么语境下工作。这就像同一个熟练工和刚毕业的学生：学生有知识，但不了解你们公司的规矩；熟手一看项目结构就知道该怎么落地。
我用它的实际感受是：生成的代码基本都在正确的“轨道”上——页面注册到app.json里，组件用微信原生组件，API调用用wx对象下对应的方法。虽然偶尔也有瑕疵，但不会出现“压根不能跑”的根源性错误。这个“上下文能力”对于微信小程序开发尤其重要，因为小程序框架里约定大于配置的东西太多了，目录结构、页面注册、生命周期、API命名，全部都有既定规范。
2. 动手之前：搞懂微信小程序的4个关键机制
2.1 双线程模型：为什么你不能像网页那样操作DOM
小程序的逻辑层和渲染层是分离的。逻辑层负责业务逻辑、数据处理，渲染层负责UI展示。两层之间通过setData建立桥梁，逻辑层数据一变，setData告诉渲染层“这部分变了”，渲染层才去更新视图。
这套模型带来两个直接影响。第一，你不能在逻辑层里直接访问页面DOM元素，所有界面更新都得走数据驱动。拿2048来说，游戏格子里的数字变化，不是“找到某个DOM节点改它的innerText”，而是修改data里的二维数组，然后WXML模板里用wx:for去渲染这个数组。第二，setData是异步的，而且每次setData都涉及两层之间的通信，频繁、大数据量的setData会直接导致页面卡顿。我优化2048手感时，把所有格子更新合并成一次setData，而不是每次移动都触发多次更新，这个改动对性能影响非常明显。
2.2 app.json 全局配置：小程序的立身之本
小程序不像网页那样靠URL路由找页面，所有页面必须在app.json里注册。pages数组的第一项就是首页。窗口样式、导航栏、tabBar、插件、权限申请，全部在这个文件里声明。
这里有个很坑的细节：如果页面文件存在，但忘了在app.json里注册，开发者工具会报错“page not found”。我遇到过两次，一次是WorkBuddy生成了新页面但更新配置时漏了，一次是我自己手动加了目录但没注册。这个问题排查起来特别容易忽略，因为报错提示不算明显，看到“not found”先怀疑路径写错了，其实多半是没注册。
另外，微信小程序的导航栏是原生的，不能在WXML里随便改变。想自定义导航栏，需要在app.json里把window的navigationStyle设为custom，但设置了之后你就得自己处理状态栏高度、胶囊按钮位置，不然刘海屏上你的导航栏会跟胶囊按钮重叠。这个后面在第4章详细讲。
2.3 微信登录与手机号能力：用户体系的入口
小程序拿用户信息的核心流程是：wx.login获取临时code，把code发给后端，后端用code去微信的code2Session接口换openid和session_key。很多新手以为wx.login返回的code就是用户身份，可以直接用，实际上code五分钟过期、只能用一次，而且必须由后端配合调用微信接口才能换取真正的用户身份。
手机号授权是另一回事。不能直接在代码里调用API拿手机号，必须用button组件加上open-type="getPhoneNumber"，用户在界面上主动点击授权，然后微信返回一个加密数据（code或encryptedData），由后端解密获取真实手机号。这个设计是为了合规，用户体验上就是“必须用户点了才算”。
我见过很多AI生成的登录代码在这一点上是错的——以为跟网页端一样调个接口就能拿到用户信息。这也是我推荐用WorkBuddy这类懂平台规则工具的原因，它生成的button代码会带正确的open-type，而不是自己瞎写一个获取手机号的函数。
2.4 本地缓存与存储：轻量数据的正确姿势
小程序的本地存储API是wx.setStorageSync / wx.getStorageSync，跟浏览器的localStorage非常像，但有几个区别：单个key限制1MB，整体没有明确上限但超过一定量会有性能问题；存储是持久化的，卸载小程序才清除；同一台手机上不同小程序的数据互不隔离（按AppID区分，但同AppID下所有用户数据都在一起）。
2048这种游戏，排行榜、音效设置、最佳成绩这种轻量数据，用wx.setStorageSync完全够了。我一开始犯过把整个棋盘状态都存进Storage的错，后来发现每次移动都写Storage，频繁IO导致卡顿明显，改成“仅退出时存一次”就稳定多了。存储不是不能用，而是要控制频率和粒度。
3. 实操：用 WorkBuddy 从零搭2048小程序并跑通上线
3.1 第一步：让 WorkBuddy 生成标准小程序工程骨架
我用的方法是先建好工作台项目，然后在项目说明里写清楚自己要什么：一个微信小程序版本的2048游戏，页面包括游戏主页、规则页，用原生小程序框架，不用第三方UI库，支持滑动操作，有本地排行榜。
WorkBuddy生成的工程结构大概是这样的：
2048-miniprogram/ ├── app.js ├── app.json ├── app.wxss ├── sitemap.json ├── project.config.json └── pages/ ├── index/ │ ├── index.wxml │ ├── index.wxss │ ├── index.js │ └── index.json └── rules/ ├── rules.wxml ├── rules.wxss ├── rules.js └── rules.json这里面每个文件都有明确职责。拿到这个骨架之后，先别急着改代码，打开app.json确认页面注册、窗口样式、sitemap配置这三项是否符合预期。sitemap.json用于配置小程序页面是否被微信索引，新项目默认全部允许就行。
project.config.json是开发者工具的项目配置文件，里面包含appid、项目名称、编译设置等。我建议生成之后立刻手动检查这个文件，特别是appid那一项。开发者工具导入项目时如果appid不对，很多API用不了——尤其是手机号授权这类能力，测试号根本无法完整验证。
3.2 第二步：实现游戏逻辑与页面渲染
2048的核心逻辑是棋盘操作：数组的移动、合并、随机生成新方块、判断游戏结束。这部分逻辑跟平台无关，WorkBuddy生成得很干脆，直接放到index.js里作为普通函数就行。
页面渲染部分就考验平台适配了。棋盘是一个4x4的二维数组，WXML里用wx:for嵌套渲染：
<view class="board"> <view class="row" wx:for="{{board}}" wx:for-item="row" wx:key="index"> <view class="cell" wx:for="{{row}}" wx:for-item="cell" wx:key="index"> <text class="cell-text value-{{cell}}">{{cell}}</text> </view> </view> </view>WXSS方面，棋盘格用rpx单位适配不同屏幕宽度，16个格子的宽高都设为固定的比例，加一些背景色区分不同数值的方块。
滑动操作可以用touchstart和touchend来监听，通过比较起始坐标和结束坐标的差值判断方向。这里有个细节：touch事件拿到的坐标是px，需要换算成逻辑方向，不用精确判断距离，只需比较x轴和y轴位移绝对值大小，就能确定是左右滑还是上下滑。
游戏核心逻辑写完之后，我做了个关键优化：把2048状态机整理成纯函数，不依赖任何小程序API。这样做有两个好处，一是WorkBuddy后续提优化方案时不会被平台API干扰，二是逻辑可以脱离开发者工具单独做单元测试。小程序开发者工具虽然自带调试器，但复杂逻辑先在Node环境跑通，效率高得多。
3.3 第三步：接入微信能力——登录、授权与数据回传
2048其实不需要登录也能玩，但我为了验证“小程序上线全流程”，还是加了一个可选的微信登录。按钮放在规则页，用户主动点击后触发wx.login：
wx.login({ success: (res) => { if (res.code) { // 把 code 传给后端，后端调用 code2Session 换取 openid that.setData({ loginCode: res.code }); } } });如果要拿手机号，前端代码就是一行button配置：
<button open-type="getPhoneNumber" bindgetphonenumber="onGetPhoneNumber"> 获取手机号 </button>这里我要强调：手机号不是在前端“拿到的”，前端只是拿到一个加密数据，必须后端配合解密。很多人写到这里就断了——拿到用户手机号了，然后呢？你得自己建后端接口、处理解密逻辑、关联用户体系。WorkBuddy能做的是把前后端交互的代码框架生成好，但真的做一个生产级后端，你还需要做token签发、会话管理、数据库设计，这些不是一个AI工具能全包圆的。
这次实战我选择了最简方案：不接自建后端，先做纯本地版本。登录状态用一个全局变量标记，手机号授权先打通前端流程，后端业务我单独用微信云开发处理。微信云开发可以免鉴权直接获取openid，对个人开发者非常友好，一步就能把一个“只有前端”的小程序升级成“有后端”的小程序，而且不用买服务器、不用备案。
云开发的获取openid方式也很简单，在云函数里通过cloud.getWXContext()就能拿到OPENID。前端只需调用wx.cloud.callFunction，一个完整的用户体系就起来了。个人开发者做小程序，我强烈建议优先考虑云开发，可以少掉一半运维工作量。
3.4 第四步：从开发者工具到真机，再到提交审核
开发者工具里跑通之后，我按这个顺序做了上线前验证：
先用“预览”功能生成一个体验版二维码，手机扫码在真机上玩几局，重点看滑动灵敏度、性能表现和是否闪退。这里要特别提醒：开发者工具里的模拟器和真机不是一回事，微信WebView在不同iOS/Android版本上的表现差异不小，尤其是CSS兼容和内存占用。2048这种小游戏对性能要求不高，但如果是复杂页面，建议至少在一台旧安卓、一台iPhone上验证。
确认没问题后，在开发者工具里点“上传”，代码会打包到微信后台，然后在微信公众平台（mp.weixin.qq.com）里把刚上传的版本设为体验版，再提交审核。审核一般1-2个工作日，个人主体的小游戏类目会稍微慢一点。我提交了两次：第一次被拒是因为页面里没有明显的“用户协议和隐私政策”入口，第二次就通过了。现在平台对合规要求很严格，哪怕是个人小游戏，隐私相关的文案也得提前准备好。
上线之后还有一个容易忽略的点：正式版的AppID和你开发时用的测试AppID是不同的。如果你用测试号开发，上线前必须把project.config.json里的appid改成正式AppID，重新编译、重新上传。这个步骤漏掉，会出现“本地一切正常，线上全挂”的经典事故。
4. 我踩过的坑：常见问题与排查实录
4.1 手机号授权弹窗为什么不出现
这个坑我折腾了大半天。代码写法完全正确，button带了open-type="getPhoneNumber"，但点击之后什么反应都没有，既不弹授权窗口，也不触发回调。
排查过程是这样的：先确认基础库版本，手机号授权需要基础库2.21.2以上，调试器里看版本没问题；再确认开发者工具模式，测试号有些能力受限，换成正式AppID重新编译；最后发现问题是button内部嵌套了一层view，微信对这个有严格限制，button内不能再嵌套别的可点击组件。
AI生成的代码里，button内部经常会被包一层view来做样式——这就是典型的“代码正确但不符合平台规则”。还好WorkBuddy能识别这类问题，我把它当成“代码审查员”帮我跑了一遍wxml规范检查。如果手写代码，建议遇到这种问题时先查微信官方文档的组件开放能力说明。
4.2 真机白屏或样式错乱，模拟器里却是好的
第一次真机预览时，模拟器里完美的棋盘在真机上裂开了——格子不对齐、背景色缺失、数字错位。仔细排查发现是WXSS的兼容性问题。
我在棋盘的样式里用了CSS Grid布局。开发者工具内置的WebView版本比较高，Grid支持的很好，但部分真机的WebView版本较老，Grid布局支持不完整，直接导致渲染崩了。换成Flexbox重写棋盘布局之后问题消失。这个经验很重要：小程序WXSS的兼容性边界比你想象的低，能用Flexbox解决的就别用Grid，能用基础属性解决的就别用高级特性。
样式类问题的排查手段有两个。一是用开发者工具的“真机调试”功能，可以看到真机上的渲染结果和控制台报错；二是用Charles抓包看资源加载是否异常。这里多说一句，小程序里用到了网络图片、字体文件这些外部资源，真机上加载不到也会表现为白屏。排查时先看是不是资源问题，通常是0%的。
4.3 本地排行榜数据丢失，重启小程序就清零
排行榜数据我存在wx.setStorageSync里，模拟器玩的时候一切正常，但真机上杀进程重启之后，排行榜不见了。
排查发现是并发问题的坑：我在onHide生命周期里写Storage，但在onShow里读取排行榜。当用户快速切换前后台时，onHide和onShow的执行顺序在某些情况下会出现竞态，导致读取的时候数据还没写完。解决方案很粗暴但也有效：所有Storage写入都走同一个函数，串行执行，避免多个异步操作同时触发写操作。另外，iOS上小程序的Storage在内存压力过大时确实可能被系统清掉一部分，所以重要数据尽量在关键节点主动落盘，不要只依赖退出时保存。
4.4 自定义导航栏在不同机型上的高度适配
我为了追求游戏页面的沉浸感，把导航栏设成了custom。问题来了：iPhone X以上机型有刘海，安全区域跟普通安卓完全不同；小程序右上角有胶囊按钮，这是系统级的，你拿不到它的DOM，只能通过API获取它的位置。
微信提供了wx.getMenuButtonBoundingClientRect()这个接口，能拿到胶囊按钮的位置信息，包括它的top、right、width、height。自定义导航栏的高度，标准算法是：状态栏高度 + 胶囊按钮的top到状态栏底部的距离 + 胶囊按钮高度 + 胶囊按钮距底部距离。我把这段逻辑封装成一个工具函数，在app启动时计算一次，存到globalData里，所有自定义导航的页面直接用这个值。
这个坑属于典型的“不踩一次永远不知道为什么别人都写这段代码”的坑。如果你不做自定义导航栏，完全不用关心；一旦做了，这段适配逻辑必须写对，否则在全面屏手机上你的导航栏会和胶囊按钮重叠，丑且难用。
5. 用 WorkBuddy 提效的几个实战心得
5.1 把需求写进“项目说明书”，而不是零散对话
WorkBuddy的工作台模式最大的好处是可以建一个项目级别的说明文档，相当于给AI一个“小程序的契约”。我的做法是：在项目根目录维护一份README，里面写清楚这个项目的技术栈、目录约定、页面清单、数据存储方案、UI风格偏好。每次让AI改代码之前先让它读一遍README，再动手改。
这个习惯的价值在于：你不需要反复提醒AI“这是微信小程序不是网页”，它每次改代码都会自动遵循既定约定。就像带实习生，最省力的方式不是每次纠正，而是给他一份团队规范文档，他在规范下工作。
5.2 用 Skill 沉淀常见操作流程
WorkBuddy有Skill的概念，就是把一个常见的操作流程固化下来，做成可复用的指令。比如我写了一个小程序发版Skill：更新版本号、修改project.config.json、检查sitemap、执行上传命令、整理发布说明。每次发版只需要调用这个Skill，AI会按固定顺序执行，不会漏步骤。
我强烈建议把“微信小程序从改代码到发体验版的流程”固化成Skill。这个流程步骤多、重复性高、容易遗漏，正好是Skill发挥价值的地方。实测下来，固化之后我发一个体验版的平均时间缩短了一半，而且不会出现“忘了改版本号”这种低级失误。
5.3 抓包和日志分开看，问题边界更清晰
调试网络请求时，我习惯用Charles抓包看小程序发出的HTTP请求，再用开发者工具的Console看逻辑层日志。两者结合能快速定位问题出在“前端没发对请求”还是“后端返回了异常数据”。
有一次手机号登录接口一直报错，Console里没有任何异常，Charles里看到接口返回了401。问题很快就定位到了后端token过期，而不是前端代码的问题。如果你只依赖开发者工具的Network面板，某些微信内部的请求（比如登录接口的code换token过程）可能看不太清，Charles在这种场景确实更从容。
只要你的小程序请求走的是普通HTTPS协议，Charles就能抓到明文请求，这对排查接口联调问题帮助巨大。抓自己开发的小程序的包，是再正常不过的调试手段。唯一要注意的是，小程序要求所有请求域名必须配置到后台白名单里，本地调试时也需要注意这个点，否则真机上所有请求都会被拦截。
结尾
这次用WorkBuddy把网页版2048搬上微信小程序，从项目搭建到审核通过，前后花了一个周末。对比几年前手写小程序的经历，最大的感受是AI工具确实把“工程搭建”和“代码生成”这两大块的效率拉高了，但它改变不了一个事实：微信小程序的平台规则还是得你自己懂，审核规范还是得你自己维护，上线的整个流程还是得你自己走通。
如果你正准备做自己的第一个小程序，我的建议是别一上来就挑战商城、社媒那类大项目，先拿一个迷你小游戏跑通“开发–预览–上传–审核–上线”的完整闭环。这个闭环跑通之后，你会发现后面做任何小程序都是重复这个框架，而你已经有了一套顺手的工作流。
另外一个小技巧：用WorkBuddy生成代码之后就养成分步提交的习惯，每完成一个小功能，就让AI在项目说明里更新一下“当前已完成功能”，这样整个开发过程里项目的状态是清晰的，不会改到后面连自己都忘了哪块做到哪一步了。别嫌这一步啰嗦，真到上线前排查问题时，这份记录能帮你省下整整一晚上的时间。
