1. 从零跑通小程序为什么小白更需要一套可复制的流程微信小程序开发这件事对零基础的人来说最劝退的往往不是写代码而是「项目怎么建、编译报错看不懂、预览二维码刷不出来、发布卡在审核」这一连串流程问题。我见过太多人卡在第一步用 Cursor 生成了一堆文件结果微信开发者工具一导入就红一片报错信息还全是英文根本不知道从哪下手。这篇内容聚焦的就是这条完整链路用 Cursor 生成代码用微信开发者工具完成项目初始化、编译、真机预览最后提审发布。适合谁适合完全没碰过小程序、但会用 Cursor 写点东西的开发者也适合之前跑过一次但流程记不全、想找一份可对照清单的人。核心检索词先明确Cursor 微信小程序开发流程、微信开发者工具编译报错、小程序真机预览二维码、小程序提审发布检查清单。这四个词基本覆盖了从建项到上线的全部关键节点。我自己的做法是把 Cursor 当成「代码生成器 排错助手」把微信开发者工具当成「运行环境 发布通道」。两者分工明确Cursor 负责写 pages、app.json、逻辑代码微信开发者工具负责编译、模拟器渲染、真机调试和上传。很多人搞混了以为 Cursor 能直接跑小程序其实不行它只是编辑器真正让代码跑起来的是微信开发者工具。所以整篇的节奏是先讲清楚项目结构和最小配置再给可复制的 app.json 和目录树然后进入编译和预览环节最后是发布前的检查清单和常见报错对照。每一步都尽量给命令、给配置、给结果说明让你照着做就能跑通。如果你之前只写过网页可以这样理解小程序的 app.json 有点像网页项目的路由配置 全局设置pages 数组就是页面路径列表第一个就是首页。wxml 类似 HTMLwxss 类似 CSSjs 就是逻辑层。理解这层映射后面看报错会轻松很多。2. 用 Cursor 生成小程序项目骨架与 app.json 最小配置这一步的目标很明确让 Cursor 帮你生成一个能跑起来的最小项目而不是一上来就堆功能。很多人失败的原因是提示词写得太贪心一次要十几个页面结果生成的文件互相引用错乱编译直接崩。我建议第一版只做两个页面一个打卡页一个历史记录页。提示词可以这样写直接复制到 Cursor 的对话里# 微信小程序需求 ## 项目概述 构建一个微信小程序用于记录工作打卡时间和查看历史记录。 ## 功能页面 ### 页面一打卡页面 - 记录上班时间和下班时间 - 显示目标工作时长 10.2 小时 - 显示本月历史打卡的平均工作时长 - 提供跳转到历史记录页面的按钮 ### 页面二历史记录页面 - 以日历形式展示历史打卡记录 - 显示本月平均工作时长 - 点击日期显示当天上下班时间 - 支持修改历史上下班时间修改后平均时长自动重算 ## 技术要求 - 所有数据保存在本地使用 wx.setStorageSync / wx.getStorageSync - 不调用任何外部 API - 适配不同屏幕尺寸生成之后你会得到一个类似这样的目录结构这是小程序的标准骨架miniprogram/ ├── app.js ├── app.json ├── app.wxss ├── project.config.json ├── sitemap.json └── pages/ ├── index/ │ ├── index.js │ ├── index.json │ ├── index.wxml │ └── index.wxss └── history/ ├── history.js ├── history.json ├── history.wxml └── history.wxss重点看 app.json这是整个小程序的入口配置最小可用版本长这样{ pages: [ pages/index/index, pages/history/history ], window: { navigationBarTitleText: 工作打卡, navigationBarBackgroundColor: #ffffff, navigationBarTextStyle: black, backgroundColor: #f5f5f5 }, style: v2, sitemapLocation: sitemap.json }这里有几个坑要提前说。第一pages 数组里的路径不要带.wxml后缀只写到文件名比如pages/index/index写错了会报「未找到入口 app.json 文件中的 pages 配置」。第二第一个页面就是启动页顺序不能乱。第三style: v2是新版组件样式建议保留不然按钮样式会和文档不一致。project.config.json 里最关键的是appid。测试阶段可以用「测试号」微信开发者工具导入项目时会让你选。正式发布必须换成你自己的正式 appid否则上传按钮是灰的。Cursor 生成代码后别急着全信。我实测下来它偶尔会把wx.getStorageSync写成wx.getStorage或者把Page({})写成Component({})这些都会导致运行时报错。生成完先扫一遍 js 文件里的 API 名确认是微信官方文档里有的。如果你用的是 Cursor 的 Agent 模式可以补一句「请检查所有 wx API 是否为微信小程序官方 API并修正拼写错误」能省不少排查时间。3. 微信开发者工具导入项目与编译报错定位项目文件有了接下来就是导入微信开发者工具。打开工具选择「导入项目」目录选到miniprogram这一层注意不是选它的父目录。AppID 那里测试阶段点「测试号」正式发布再换。导入后工具会自动编译一次。如果一切正常模拟器里会直接渲染出打卡页面。但小白第一次导入大概率会遇到编译报错。下面这张对照表是我自己踩过的坑你可以直接拿来查报错信息原因解决方式未找到入口 app.json 文件导入目录选错选到了父级重新导入目录选到含 app.json 的那一层pages/index/index 未找到pages 路径写错或文件缺失检查 app.json 的 pages 和实际文件是否一致wx.getStorageSync is not a functionAPI 拼写错误改成 wx.getStorageSync注意大小写app.json 解析错误JSON 里有注释或多余逗号删掉注释检查最后一个属性后不能有逗号编译报错Unexpected tokenjs 文件里有语法错误看报错行号通常是括号或分号问题模拟器白屏无报错首页 js 里 Page 未注册或 data 未定义检查 index.js 是否有 Page({ data: {} })每次编译前我建议先点一下工具上的「清缓存」→「清除全部缓存」再点「编译」。这一步能避免很多「改了代码但模拟器没更新」的假问题。尤其是改了 app.json 之后不清缓存有时候新页面不生效。编译命令这块微信开发者工具本身是图形化操作没有命令行编译的强制要求。但如果你用 CI 或者想自动化可以用微信官方提供的miniprogram-ci不过对小白来说前期先用工具里的「编译」按钮就够了别过早引入复杂度。真机预览是这一步的重点。点工具右上角的「预览」会生成一个二维码。用微信扫这个二维码就能在手机上打开你的小程序。注意预览用的是测试号或正式 appid 对应的权限如果扫码后提示「该小程序未上线」说明你用的是测试号这是正常的测试号只能自己扫码预览。如果预览二维码一直刷不出来先检查网络再检查工具是否登录了微信账号。有时候工具掉登录了预览按钮点了没反应重新扫码登录即可。还有一个高频问题真机上样式和模拟器不一致。这通常是因为模拟器默认是 iPhone 尺寸而你手机是安卓。解决办法是在工具的「模拟器」面板里切换设备型号多试几个尺寸确保布局不塌。4. 真机预览、上传代码与提审发布全流程真机预览通过后就可以进入发布环节。发布分三步上传代码、设置体验版、提交审核。第一步上传代码。在微信开发者工具右上角点「上传」会弹出一个窗口让你填版本号和项目备注。版本号建议用1.0.0这种语义化格式备注写清楚这次改了什么比如「首版打卡页 历史页」。上传成功后代码就进了微信公众平台的「开发版本」里。这里有个硬性前提必须使用正式 appid。测试号是没法上传的上传按钮会提示你先绑定正式 appid。所以如果你打算发布提前在微信公众平台注册好小程序拿到 appid填到 project.config.json 里。第二步登录微信公众平台进入「管理」→「版本管理」。你会看到刚上传的开发版本。点「选为体验版」生成体验版二维码。这个二维码可以发给朋友或测试人员让他们在微信里扫码体验。体验版和正式版的区别是体验版不需要审核但只有被添加为体验成员的人才能扫。第三步提交审核。在版本管理里点开发版本右侧的「提交审核」。提交前会要求你填写一些信息比如功能页面路径、测试账号如果有登录功能。因为我们这个打卡小程序是纯本地存储没有登录所以测试账号可以留空。提交后就是等审核。审核期间你可以在「审核版本」里看到状态。审核通过后点「发布」小程序就正式上线了。上线后任何人都能通过搜索或扫码打开。发布前检查清单我整理成下面这几条建议逐条核对app.json 里 pages 路径全部正确无多余逗号project.config.json 里 appid 是正式 appid所有 wx API 拼写正确无wx.getStorage这类错误本地存储的 key 命名统一避免读写不一致真机上至少完整走一遍打卡和历史修改流程版本号和备注填写清晰方便回滚体验版至少让一个人扫码验证过血的教训做好版本管理。每次上传都写清楚版本号和备注万一线上出问题可以在版本管理里回滚到上一个版本。我见过有人上传时备注写「更新」结果出问题后根本不知道回滚到哪个版本。另外审核被拒最常见的原因是「功能不完整」或「页面空白」。所以提交前一定要在真机上把每个页面都点一遍确保没有白屏。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth虽然我们这个打卡小程序是纯本地存储不涉及网络请求但很多人在用 Cursor 生成代码时会不小心引入一些需要后端或第三方服务的逻辑这时候就会遇到下面这些报错。我把它们整理出来方便你对照排查。401 报错通常出现在你调用了某个需要鉴权的接口。比如 Cursor 生成的代码里如果带了wx.request去请求某个 API而你没配 token就会返回 401。解决办法是检查代码里有没有wx.request如果有要么删掉要么补上正确的鉴权头。纯本地存储的小程序不应该出现 401。local proxy failed这个报错一般和开发者工具的代理设置有关。如果你在工具里开了「代理设置」为手动但代理地址不可用就会报这个。解决办法是进「设置」→「代理设置」改成「不使用任何代理」然后重新编译。注意这里只是工具的网络设置不涉及任何其他操作。reading choices这个报错通常出现在 js 里对一个 undefined 变量取属性。比如res.data.choices但res.data是 undefined。排查方法是看报错行号确认那个变量是否真的被赋值了。常见于 Cursor 生成的异步代码里回调没执行就取了值。OAuth 相关报错如果你在代码里看到OAuth字样说明 Cursor 可能给你生成了需要登录授权的逻辑。小程序里做登录一般用wx.login换 code再走自己的后端。如果你没有后端就把这段逻辑删掉改成纯本地存储。不要在小程序里直接写 OAuth 流程那不是小程序的常规做法。排查这些报错的通用思路是先看报错行号再看那一行用了什么变量或 API然后确认这个变量是否被正确初始化、这个 API 是否是小程序官方支持的。Cursor 可以帮你定位但最终判断还得靠你自己对小程序 API 的熟悉程度。如果你在接入过程中需要管理多个 key 或模型配置可以用 TaoToken 的 API Keys 页面统一管理地址是 https://taotoken.net/api-keys 配合接入文档 https://taotoken.net/doc 一起看能少走弯路。6. 从建项到发布把流程固化成自己的检查清单跑通一次之后最重要的是把流程固化下来。我自己的做法是建一个checklist.md每次新建小程序项目就复制一份按顺序打勾。内容就是前面那几节的核心步骤建目录、写 app.json、导入工具、清缓存编译、真机预览、上传、设体验版、提审。Cursor 在这个过程中扮演的是「加速器」不是「替代品」。它能帮你快速生成页面结构和逻辑但编译、预览、发布这些环节必须回到微信开发者工具里完成。两者配合效率最高。如果你后续想接入模型能力比如让打卡小程序支持自然语言记录可以走 TaoToken 的模型对话接口地址是 https://taotoken.net/models 先在小程序里用wx.request调通再考虑上线。长期做编码或 Agent 类项目的话Coding Plan 会更划算地址是 https://taotoken.net/coding-plan 。最后给一个实用技巧每次改完代码先点「清缓存」再点「编译」然后真机预览确认最后才上传。这个顺序能帮你把问题拦在发布之前。发布不是终点能稳定回滚才是。