我用 AI 做了一个 Skill专门用来跑通微信小程序从需求到首次运行的完整流程。这个 Skill 不是一段让我复制粘贴的 Prompt而是一套可复用的指令文件放到支持 Skill 机制的 AI 编程工具后AI 会按阶段完成需求拆分、项目骨架、页面开发、配置检查、本地编译和真机预览。第一次用的时候我也担心它会不会只是把代码写完就结束实际跑通之后发现真正决定首次运行成败的往往是 AppID、页面注册、调试开关这些细节。所以下面按实际落地顺序把 Skill 的设计思路、文件结构、使用步骤和踩过的坑拆一遍。如果你正在做微信小程序或者想用 AI 编程工具减少“代码写完但跑不起来”的重复调整这篇内容会更适合你。我会尽量把每一步为什么这么做、做到什么程度可以继续下一阶段都写清楚。1. 为什么不能只让 AI 写代码还要给 AI 定义“流程”1.1 微信小程序“首次运行”失败的根源不是代码很多人第一次用 AI 开发微信小程序会让 AI 直接写一个带登录、列表、详情页的项目。AI 生成得很快代码看起来也很完整但导入微信开发者工具后经常出现几种情况编译报错提示某个页面路径不存在。模拟器白屏控制台没有明确错误。页面能打开但请求接口直接失败。真机预览时登录不了用户信息获取失败。底部 tabBar 图片不显示或者页面路由乱跳。这些问题的根源往往不是 AI 写的业务逻辑有问题而是小程序的运行链路比普通网页更严格。页面需要在app.json里注册每个页面的wxml、wxss、js、json文件必须放在正确的路径下真机调试还需要 AppID 匹配、基础库版本匹配、权限设置匹配。让 AI 直接生成代码等于跳过了这些前置检查。1.2 Skill 和普通 Prompt 的本质差异普通 Prompt 是“帮我做一个 XX 小程序”AI 只能凭训练经验猜测你的需求生成一版代码。这种模式在生成单个页面时没问题但很难保证项目的整体结构、配置和调试步骤是正确的。Skill 不一样。我做的这个 Skill 本质上是一份给 AI 看的开发流程定义。它里面写清楚了接到需求后先拆页面还是先写页面。app.json里的页面路径怎么维护。本地调试时哪些开关要打开。首次编译需要检查哪些关键节点。遇到报错时按什么顺序排查。AI 加载 Skill 之后不再是一个“接到指令就写代码”的对话助手而是一个“按流程执行任务”的工程助手。它每一步都会先看当前阶段目标再动手最后输出检查结果。1.3 这个 Skill 适合谁不适合谁我建议这几类人重点参考独立开发者一个人要管需求、设计、开发、测试Skill 能把开发流程标准化减少遗漏。前端工程师日常写代码没问题但想用 AI 提速Skill 可以把你自己的规范变成可复用文件。产品同学想快速做出小程序原型验证想法能不能跑通。如果你是完全没有接触过编程的纯新手第一次用的时候还是需要一个会看控制台报错的人陪跑。Skill 能提高成功率但不能替代你对小程序基础概念的了解。2. 准备环境在不折腾的环境里先跑起来2.1 我的基础环境和最低配置建议先说环境。我日常用的组合是操作系统Windows 和 macOS 都跑过。AI 编程工具支持自定义 Skill 的命令行 AI 工具例如 Claude Code、Codex 这类能在项目里读取指令文件。微信开发者工具稳定版即可不需要追最新的 nightly。Node.js大多数脚手架工具会用到建议装 LTS 版本。低配机器能不能跑能。我写过的最小案例是在一台只有 8GB 内存的笔记本上完成的。关键在于不要把模拟器、开发者工具、AI 工具全开满编译时尽量关掉其他大应用。小程序的编译工具本身不算重但如果你让 AI 同时在后台跑很多任务内存会很快吃紧。2.2 Skill 文件的放置方式和目录结构不同 AI 工具的 Skill 目录名可能不一样我自己的习惯是把 Skill 放在项目根目录下一个固定位置然后在项目里引用。示例结构如下my-miniprogram/ ├── .ai/ │ └── skills/ │ └── weapp-dev/ │ └── SKILL.md ├── miniprogram/ │ ├── app.js │ ├── app.json │ ├── app.wxss │ └── pages/ │ └── index/ │ ├── index.js │ ├── index.json │ ├── index.wxml │ └── index.wxss └── project.config.json这里SKILL.md就是 Skill 的核心文件。它不一定非要叫这个文件名具体取决于你用的工具但原理一致AI 在项目里找到这个文件后会把里面的指令读入上下文作为本次任务的执行约束。SKILL.md里我一般写入这段信息--- name: weapp-dev description: 微信小程序从需求到首次运行的开发流程 --- # 阶段1需求拆分 - 列出页面列表 - 列出数据来源 - 列出涉及权限 - 确认基础库版本 # 阶段2生成项目骨架 - 检查 app.json 中的 pages - 确保每个页面目录结构完整 - 检查 project.config.json 中的 appid # 阶段3页面开发 - 先 wxml再 wxss再 js - 所有请求接口统一封装 - 登录态统一管理 # 阶段4本地验证 - 编译通过 - 模拟器可见页面 - 控制台无红色报错 - 真机预览二维码可打开不要小看这些步骤。AI 每次拿到需求后会照着这个流程走一遍而不是只凭“用户说开发一个XX页面”就冲到代码里。2.3 原生小程序与 uniapp/HBuilderX 的差异如果你用的是 uniapp 或 HBuilderX 开发微信小程序目录结构和编译方式会不一样。Skill 里的流程仍然可以用但第 2 阶段的项目骨架必须调整。原生的微信小程序项目核心配置文件是app.json、project.config.json、app.js和app.wxss。而 uniapp 项目根目录下通常有一个src目录页面放在src/pages另外有manifest.json用来配置小程序 AppID。HBuilderX 会把 uniapp 代码编译成微信小程序代码编译后的目录通常是dist/dev/mp-weixin。我踩过的一个坑是让 AI 按原生小程序结构去改 uniapp 项目结果它把src/pages下的页面复制到了miniprogram/pages导致 HBuilderX 编译时找不到页面。所以如果你用 uniapp务必在 Skill 里明确写清楚项目类型和目录结构不要让 AI 凭经验猜测。3. 从需求到项目骨架AI 该在最初阶段问清楚什么3.1 需求拆分清单页面、数据、权限、基础库不要一上来就让 AI 生成代码。先把需求拆清楚这是 Skill 里最重要的一步。我会要求 AI 在生成任何文件之前先输出一份需求拆分表至少包含页面列表首页、详情页、个人中心等。数据来源本地写死、后端接口、云开发、第三方 API。用户权限是否登录、是否获取手机号、是否获取位置。基础库版本目标用户用的微信版本决定 API 是否可用。举个例子如果你要做一个小程序表单需求拆分表可能是项目内容页面表单填写页、提交成功页数据表单数据通过接口提交到后端权限不需要登录但需要验证手机号基础库2.30.0 以上有了这张表AI 才知道代码里应该调用哪些 API而不是把所有能用到的 API 都堆上去。微信小程序很多 API 有最低基础库要求如果目标用户微信版本过低功能会静默失败。3.2 先让 AI 生成可编译的最小骨架需求拆分完成之后进入生成骨架阶段。此时我要求 AI 只做最小可运行版本不要加太多业务代码。一个原生微信小程序的最小骨架通常包括{ pages: [ pages/index/index, pages/submit/submit ], window: { navigationBarTitleText: 示例小程序, navigationBarBackgroundColor: #ffffff, navigationBarTextStyle: black }, sitemapLocation: sitemap.json }这个文件看起来简单但它决定了小程序能进入哪个页面。AI 如果新增了一个页面但没有在pages数组里注册编译时会直接报错“页面路径未找到”。所以我让 Skill 规定每次新增页面AI 必须同步修改app.json并且编译一次确认无报错再继续下一个页面。这个规则非常管用。3.3 用一个“空页面验证法”确认编译链路骨架生成后先用一个空页面验证编译链路而不是直接写业务。具体做法是新建一个只包含index页面的最小项目。导入微信开发者工具。编译一次确认模拟器能显示一个空白页面。确认控制台没有红色报错。在这个基础上再加页面、再开发业务。这个方法的原理很简单如果最小骨架都跑不起来那问题大概率出在项目配置、文件路径或依赖安装上而不是业务代码。先排除环境问题再开发功能排查范围会小很多。我实际测试时发现AI 生成的代码里最容易出问题的就是路径大小写不一致。比如pages/Index/index和pages/index/index在 macOS 上可能能编译但到 Linux 或真机上就会出问题。Skill 里最好加一条规则所有页面目录和文件名统一小写不要依赖大小写区分文件。4. 首次运行的正确顺序编译、调试、真机预览4.1 微信开发者工具导入项目的关键设置AI 生成的是本地代码最终要交给微信开发者工具来编译和运行。导入项目时有几个地方必须检查。第一选择项目目录。如果你用原生小程序目录应该是包含project.config.json的根目录而不是miniprogram子目录。如果你导入的是 uniapp 编译后的dist/dev/mp-weixin目录选择会不一样。第二AppID。这里要看实际情况。如果你只有测试号就在project.config.json里填测试号或者在开发者工具里选择“测试号”。如果企业项目已经分配了 AppID一定要填真实 AppID否则wx.login、订阅消息、云开发等能力都会有问题。第三本地设置。在微信开发者工具的“详情 - 本地设置”里建议把“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”打开。这里的原理是开发阶段可能使用 localhost 或 IP 访问本地接口如果不打开这个开关所有 request 请求都会被拦截。注意这个开关只用于开发调试正式上线前一定要在后端配置合法域名否则真机访问线上接口会失败。4.2 用一个小表单验证页面渲染和数据请求我建议用一个小表单作为首次运行的测试用例。表单不需要复杂只需要包含一个输入框、一个单选框、一个提交按钮。单选框在小程序里是radio-group和radio我用它有两个原因一是能验证事件绑定是否正确二是能验证表单组件和样式的渲染情况。示例代码大概是这样form bindsubmitonSubmit view input namenickname placeholder请输入昵称 / /view radio-group namegender label radio valuemale checked /男 /label label radio valuefemale /女 /label /radio-group button form-typesubmit提交/button /form对应的 JS 里只需要接收表单值然后调用一个接口提交。如果提交时请求失败你能很清楚地看到问题是出在wx.request的域名配置、参数格式还是后端接口。这里有一个容易被忽略的点如果wx.request请求的返回体不是 JSON或者后端没有返回正确的Content-Type小程序端可能拿不到data。Skill 里最好明确写入所有接口返回必须使用 JSON 格式且错误信息也要放在 JSON 里不能只返回非 200 的 HTTP 状态码。4.3 登录、授权、用户信息获取的常见理解误区很多小程序项目会把“登录”和“获取用户信息”混在一起。实际上wx.login、wx.getUserProfile、wx.getUserInfo是三个不同的能力Skill 里必须分开对待。wx.login用来获取临时登录凭证 code这个 code 要发给后端后端用 code 换 openid 和 session_key。它不涉及用户昵称和头像。wx.getUserProfile用来获取用户头像和昵称需要用户主动点击按钮授权。用户拒绝之后代码会直接走 fail 回调不能再弹窗。wx.getUserInfo在老版本基础库中可用但在新版本中已经不能主动弹授权框了。我之前遇到一个案例小程序获取登录后的微信用户失败一直找不到原因。后来看日志才发现代码在wx.login成功后直接调用了wx.getUserProfile但没有把按钮触发放在用户点击事件里。微信要求getUserProfile必须由用户点击行为触发于是调用被拦截。所以 Skill 里应该加入规则先梳理登录流程是“静默登录”还是“登录并获取资料”。如果需要用户资料必须由用户点击按钮触发。用户拒绝授权后要允许用户重新点击授权不能直接白屏。4.4 真机预览不是最后一步而是联调的一环很多人习惯在模拟器里跑通就算完成但模拟器能跑通真机不一定能。真机预览常见的问题包括字体、导航栏、安全区域适配不同。本机 localhost 地址在手机端不可访问需要改成局域网 IP。手机和电脑不在同一局域网预览二维码无法正常连接。AppID 是测试号部分能力被限制。我一般建议把真机预览放在开发中期而不是最后。第一次跑通空页面之后就尝试预览如果预览失败说明环境有问题越早发现越容易解决。真机上如果白屏可以先打开调试模式看wx.request和页面加载日志。如果只是样式不对优先检查rpx单位和safe-area。如果按钮点击没反应优先看事件绑定和基础库版本。5. 把 Skill 从“能用”调成“好用”迭代检查清单5.1 把验证步骤写进 SKILL.md而不是靠记忆第一版 Skill 只需要包含流程框架。第二版我会把验证步骤也写进去因为 AI 在生成代码后默认不会主动检查。我在SKILL.md里会增加一个“验证清单”段落# 验证清单 - [ ] app.json 页面路径与 pages 目录一致 - [ ] project.config.json 中的 appid 非空 - [ ] 每个页面的 wxml、wxss、js、json 文件都存在 - [ ] wx.request 使用 https 或已开启开发调试开关 - [ ] 无红色编译报错 - [ ] 模拟器能显示页面 - [ ] 真机预览能打开AI 每完成一个阶段就逐项检查一遍。这样做的好处是问题在靠近发生的位置就被发现而不是攒到最后一次性排错。5.2 把错误知识库加进去报错、原因、修复Skill 不只可以约束流程还可以记录常见报错。运行项目时遇到问题我会把“现象 - 原因 - 解决方式”追加到 Skill 文件里。例如## 常见错误 ### request:fail - 现象请求不到数据 - 原因开发环境未打开不校验域名或后端地址不可达 - 解决检查本地设置检查接口地址 ### page not found - 现象编译报错找不到页面路径 - 原因app.json 未注册新页面 - 解决把页面路径添加到 pages 数组 ### getUserProfile:fail - 现象点击授权后无反应 - 原因授权必须由用户点击事件触发 - 解决确认调用位置在事件回调内这些内容以后会成为 AI 排查问题的依据。遇到同类报错时AI 能直接按记录处理不需要重新猜。5.3 多人协作时的命名、输出和回滚约定如果你是一个人用Skill 可以随意调整。但如果你要把 Skill 分享给团队就要约定几个核心规则项目目录命名统一miniprogram或src二选一。页面命名统一小写pages/index/index而不是pages/Index/index。接口封装统一所有wx.request必须走同一个request.js不能在页面里散着写。每次修改前用git commit或一个可回滚的副本保存防止 AI 把整个项目改乱。我在团队里使用 Skill 时会在项目根目录加一个AGENTS.md或README.md把 Skill 中的核心规则同步写一份。这样即使其他人没用同一个 AI 工具也能知道约定是什么。6. 常见卡点排查你能想到的启动问题基本都在这里6.1 请求不到数据域名白名单、调试开关、后端接口wx.request失败是最常见的问题。排查顺序我一般这样走看控制台具体报错信息。确认开发者工具“不校验合法域名”是否打开。确认接口地址是不是https开发环境允许http时也要开调试开关。在电脑浏览器直接访问接口看后端是否正常。查看后端返回的格式是否为 JSON。检查手机端真机调试时是否能访问到后端地址。很多“接口通但小程序拿不到数据”的问题不是跨域而是小程序的客户端环境里没有开启域名校验开关。后端能访问但小程序端直接被本地策略拦截了。6.2 页面样式和导航栏适配机型与基础库页面样式问题更多是适配问题不是逻辑问题。这里有两个常见点。第一顶部导航栏高度。不同机型的系统导航栏高度不一样不要写死一个固定值。小程序的胶囊按钮位置可以通过wx.getMenuButtonBoundingClientRect()获取再结合wx.getSystemInfoSync()计算导航栏高度。Skill 里如果涉及自定义导航栏应该直接把这个计算方式写进去。第二底部安全区域。iPhone 底部有 home indicator用env(safe-area-inset-bottom)或小程序的safe-area配置处理避免按钮被遮挡。6.3 推送、定位、H5 跳转等扩展场景的边界首次运行不用着急做推送和定位但如果你在需求拆分阶段发现可能涉及要提前想清楚边界。订阅消息不是“想发就发”。用户需要主动订阅而且每次订阅的有效次数可能有限。如果项目需要小程序推送消息方案要区分“表单订阅”“一次性订阅”“长期订阅”等不同场景。Skill 里至少要求 AI 先确认后端有没有存储用户 openid以及用户有没有完成订阅授权。定位能力也要分开看。微信小程序里可以用wx.getLocation获取当前位置但需要用户授权还需要在app.json里声明requiredPrivateInfos。注意H5 页面放到小程序web-view里之后不能直接调用小程序当前经纬度。H5 如果要拿到经纬度通常需要小程序端获取后把坐标通过 URL 参数传给 H5 页面或者使用微信 JS-SDK 的能力但这又依赖公众号网页授权配置复杂度会上升。6.4 从现象到原因的排查顺序最后给一个通用排查表。每次小程序跑不起来我基本按这个顺序处理。现象优先检查常见原因编译报错页面找不到app.json的 pages 数组新页面未注册模拟器白屏控制台日志、页面路径入口页路径错误或 JS 报错请求失败本地调试开关、域名配置未打开域名校验或接口不可达登录失败wx.login是否返回 codeAppID 与后台服务不一致用户信息获取失败是否由用户点击按钮触发getUserProfile被非用户操作调用真机预览失败手机和电脑是否同一局域网局域网隔离或 AppID 权限不足样式错乱机型、基础库、rpx 适配自定义导航栏或安全区域未处理排查时不要一次性改多个地方。只改一个变量重新编译看你改完之后控制台有没有变化。我见过很多同学同时改了 AppID、域名、页面路径结果报错还在却不知道是哪一步起作用了。先固定环境再逐步排查是最省时间的做法。最后留几个我自己排查时会优先看的点AppID 是否匹配页面路径有没有注册控制台日志有没有红色报错请求是否开了不校验域名真机预览有没有开启调试。把这五点看完比翻几十条帖子快得多。Skill 的价值不是让 AI 万能而是让 AI 和开发者在同一个流程里工作减少“代码写完但跑不起来”的重复调整。