1. 背景与核心概念1.1 什么是 Skill一个全新的 AI 开发范式在传统的软件开发流程中从需求分析、原型设计、UI 开发、后端联调、测试到最终部署上线往往需要多个角色、多轮迭代、多套工具配合才能完成一个最小可用产品。对于微信小程序这种前端与后端、移动端与微信生态深度耦合的场景技术栈杂、坑点多、调试流程长很多开发者尤其是个人开发者或小团队常常在环境配置和基础功能开发阶段就耗费了大量精力。“Skill” 这个词在最近的技术圈中逐渐被赋予了一个新的定义它不是指游戏里的技能也不是指某个人的专业技能而是一种由 AI 大模型驱动的、可复用的自动化开发能力单元。简单来说你可以把 Skill 理解为一个“AI 开发助手插件”——它能够根据你的自然语言描述理解你的业务需求然后自动生成符合你技术栈的完整代码、配置文件、依赖说明甚至直接帮你搭建好可运行的项目骨架。当 AI 与微信小程序开发结合这个 Skill 就是一整套从“我想做一个什么样的小程序”到“小程序已经能在微信开发者工具中正常跑起来”的完整流程。它不再是简单的代码补全或片段生成而是需求理解、架构设计、代码生成、环境配置、依赖安装、错误修正的全链路自动化。1.2 为什么需要这个 Skill解决开发者的真实痛点在实际开发中微信小程序入门并不难但要做到“从零到首次运行”中间有大量重复性工作和技术细节项目初始化繁琐每次新建项目都要配置 appid、域名白名单、合法域名、SSL 证书等。页面与组件结构重复每个页面都要写 wxml、wxss、js、json 四个文件且逻辑相似。API 调用与权限处理用户登录、获取手机号、接口超时、数据缓存等每个点都可能踩坑。版本兼容与适配微信基础库版本、iPhone 刘海屏适配、自定义导航栏高度等。调试与测试成本高真机调试、预览、上传代码每个环节都可能出现不可预期的问题。而 AI 开发 Skill 正是为了解决这些问题而生。它能够理解你的自然语言需求你说“我要做一个 AI 心理咨询助手小程序”它能自动拆解出核心功能模块。生成最小可行代码包括页面、组件、API 调用、数据管理等。自动处理依赖与配置安装 npm 包、配置 webpack、设置合法域名等。提供实时调试建议遇到报错时能根据错误信息给出修复方案。1.3 适用读者与学完后的收获本文适合以下读者群体微信小程序初学者想快速跑通一个完整的小程序而不是卡在环境配置上。全栈开发者希望能用 AI 加速日常开发流程减少重复劳动。产品经理或创业者想快速验证自己的想法看到可用的 Demo 再决定是否投入完整开发。AI 开发爱好者对 AI 编程、大模型落地实践感兴趣想了解最新的开发范式。学完本文后你将能够掌握使用 AI 开发 Skill 完成微信小程序从需求分析到首次运行的完整流程。理解 AI 生成代码的常见模式与局限性知道如何高效地与 AI 协作。独立完成一个包含用户登录、数据展示、页面跳转等核心功能的小程序初始版本。掌握微信小程序开发中的常见坑点和最佳实践避免重复踩坑。2. 环境准备与版本说明2.1 开发环境要求在开始之前请确保你的电脑满足以下基础环境要求。版本号以本文撰写时的常见稳定版本为准实际开发中请根据项目需求灵活调整。项目推荐版本说明操作系统Windows 10 / macOS 12 / Linux Ubuntu 20.04主流系统均可建议 64 位Node.js18.x LTS 或 20.x LTS用于构建工具和 npm 包管理微信开发者工具最新稳定版 1.06.xxx下载地址微信公众平台官网微信小程序 AppID已注册的小程序 AppID未注册可到 mp.weixin.qq.com 注册代码编辑器VS Code 微信开发者工具VS Code 推荐安装 ESLint、Prettier、vscode-wechatAI 开发平台支持自然语言生成代码的 AI 平台如 OpenAI API、Claude API、文心一言等按需选择2.2 注册与准备工作第一步注册微信小程序账号如果你还没有微信小程序账号需要先到 微信公众平台 完成注册。注册流程如下点击“立即注册”选择“小程序”。填写邮箱、密码、验证码完成邮箱激活。选择主体类型个人、企业、媒体等个人开发者建议选择“个人”。完善小程序信息包括名称、头像、介绍等。注册成功后进入“开发” - “开发设置”获取你的 AppID。注意AppID 是微信小程序的身份标识后续所有开发环节都需要用到。个人开发者申请的 AppID 部分权限受限如支付、附近的小程序等但开发学习完全够用。第二步下载并安装微信开发者工具微信开发者工具是官方提供的集成开发环境支持代码编辑、调试、预览、上传等功能。请到微信公众平台下载对应你操作系统的最新版本。安装完成后用微信扫码登录即可。第三步准备 AI 开发 Skill 环境AI 开发 Skill 的使用方式有很多种本文采用以下通用方案使用支持大模型 API 调用的开发环境如 Python 环境 OpenAI 库。或者使用 AI 编程助手插件如 Cursor、Codex、GitHub Copilot 等。或者使用支持自然语言交互的网页版 AI 平台如 ChatGPT、Claude 等。本文以“使用 API 调用 AI 模型生成代码”为例你可以在本地创建一个 Python 脚本调用 AI 接口生成小程序代码。如果你对 Python 不熟悉也可以直接使用 AI 聊天界面手动将生成的代码复制到项目中。2.3 项目结构规划在开始生成代码之前我们先规划一下微信小程序的标准项目结构。一个典型的微信小程序项目根目录下包含以下文件和文件夹mini-program-demo/ ├── app.js # 小程序全局逻辑 ├── app.json # 小程序全局配置 ├── app.wxss # 小程序全局样式 ├── project.config.json # 项目配置文件开发者工具读 ├── pages/ # 页面文件夹 │ ├── index/ # 首页 │ │ ├── index.js │ │ ├── index.json │ │ ├── index.wxml │ │ └── index.wxss │ └── logs/ # 日志页 │ ├── logs.js │ ├── logs.json │ ├── logs.wxml │ └── logs.wxss ├── utils/ # 工具函数 │ └── util.js ├── images/ # 图片资源 └── style/ # 公共样式这个结构是微信小程序的基础骨架后续所有页面、组件、API 调用都会在此基础上扩展。AI 生成代码时也会遵循这个结构来组织文件。3. 核心原理拆解AI 如何理解需求并生成小程序代码3.1 AI 理解需求的流程AI 开发 Skill 的核心能力是“自然语言转代码”。它并不是真正理解你的业务而是通过大量的训练数据学会了从文本描述到代码输出的映射关系。当你说“我想做一个 AI 心理咨询助手小程序”时AI 内部大致会经历以下四个步骤意图识别解析输入文本找出核心关键词如“AI”、“心理咨询”、“小程序”、“助手”。功能拆解基于常见的微信小程序功能模式拆解出协议所需的功能模块比如用户登录与授权获取用户信息首页展示聊天界面或咨询入口对话功能输入框 消息列表数据存储本地缓存或云开发数据库技术选型根据功能模块选择合适的技术方案。例如用户登录优先使用 wx.login 后端接口数据存储使用本地缓存或微信云开发数据库。代码生成按照微信小程序的开发规范生成对应的文件结构、配置文件、页面代码、API 调用代码。3.2 AI 生成代码的常见模式模式一生成完整项目骨架这种模式最适合“从零开始搭建项目”。你只需要输入需求描述AI 就会一次性生成整个 project 的所有文件。例如用户输入帮我生成一个微信小程序项目首页是一个聊天界面包含一个输入框和一个发送按钮点击发送后消息显示在列表中。AI 会生成app.json配置页面路径、窗口样式、tabBar 等。pages/index/index.wxml聊天界面模板。pages/index/index.wxss聊天界面样式。pages/index/index.js输入框事件、发送逻辑、消息列表渲染。pages/index/index.json页面配置。模式二生成特定功能模块这种模式适合在已有项目基础上添加新功能。例如用户输入在现有项目的 pages/user 页面上添加一个“获取用户手机号”的按钮点击后调用微信 API 获取手机号并保存到本地缓存。AI 会生成以pages/user文件夹为目标的修改后代码并提示你需要在app.json中注册该页面如果尚未注册。模式三生成 API 调用与数据处理逻辑这种模式适合后端接口联调或数据展示。例如用户输入写一个微信小程序页面用于展示一个文章列表通过 wx.request 调用 GET 接口 https://api.example.com/articles 获取数据并在页面渲染。AI 会生成完整的页面代码包括 loading 状态、错误处理、列表渲染、下拉刷新等。3.3 AI 辅助开发的核心原则可控与可解释虽然 AI 生成代码的能力越来越强但你不能完全依赖它。以下是几个核心原则能帮助你更好地与 AI 协作先拆解再生成在给 AI 输入需求之前自己先拆解一下功能模块。拆解得越细AI 生成的代码越精准。分步生成逐步验证不要一次性让 AI 生成整个项目这样容易出错且难以调试。建议先让 AI 生成项目骨架跑通后再生成页面最后生成逻辑。理解代码而非盲复制AI 生成的代码不一定是最优的甚至可能有 bug。你需要理解每一行代码的作用尤其是 API 调用和权限处理部分。保留人工审核环节涉及用户数据、支付、敏感信息的功能必须由人工审核代码安全性不能直接上线。4. 完整实战案例用 AI 开发一个“AI 心理咨询助手”小程序4.1 需求描述我们希望开发一个微信小程序核心功能如下首页显示一个简单的聊天界面包含一个消息列表和一个输入框。用户在输入框中输入文字点击“发送”按钮消息出现在列表中。实现用户登录功能获取用户的昵称和头像并显示在聊天界面的右上角。使用本地缓存保存聊天记录下次打开小程序时还能看到历史消息。页面样式简洁类似微信聊天界面。4.2 第一步让 AI 生成项目骨架首先我们向 AI 输入以下需求请帮我生成一个微信小程序项目骨架命名为 ai-chat-helper。要求 - 项目包含两个页面首页index和用户页user。 - 首页是聊天界面包含消息列表和输入框。 - 用户页用于显示用户信息昵称、头像。 - 全局配置app.json中设置窗口背景色为白色导航栏标题为AI 心理助手。 - 不需要tabBar。 - 不需要网络请求所有数据存本地缓存。AI 会生成以下文件以 OpenAI 的 ChatGPT 或 Claude 为例实际输出可能略有差异但核心逻辑一致文件app.json{ pages: [ pages/index/index, pages/user/user ], window: { navigationBarTitleText: AI 心理助手, navigationBarBackgroundColor: #ffffff, navigationBarTextStyle: black, backgroundColor: #ffffff }, sitemapLocation: sitemap.json }文件pages/index/index.wxmlview classcontainer view classmessage-list view wx:for{{messages}} wx:keyindex classmessage-item {{item.role user ? user : ai}} view classavatar image src{{item.role user ? userInfo.avatarUrl : /images/ai-avatar.png}} modeaspectFill/image /view view classbubble{{item.content}}/view /view /view view classinput-area input classinput typetext placeholder输入你的问题... bindinputonInput value{{inputValue}} / button classsend-btn bindtapsendMessage发送/button /view /view文件pages/index/index.wxss.container { display: flex; flex-direction: column; height: 100vh; } .message-list { flex: 1; overflow-y: auto; padding: 20rpx; } .message-item { display: flex; margin-bottom: 30rpx; } .message-item.user { flex-direction: row-reverse; } .avatar { width: 80rpx; height: 80rpx; border-radius: 50%; overflow: hidden; margin: 0 20rpx; } .avatar image { width: 100%; height: 100%; } .bubble { max-width: 60%; padding: 20rpx 30rpx; border-radius: 20rpx; background-color: #f0f0f0; font-size: 28rpx; line-height: 1.5; } .message-item.user .bubble { background-color: #95ec69; } .input-area { display: flex; padding: 20rpx; border-top: 1px solid #eee; align-items: center; } .input { flex: 1; height: 80rpx; border: 1px solid #ddd; border-radius: 40rpx; padding: 0 30rpx; font-size: 28rpx; } .send-btn { margin-left: 20rpx; padding: 0 40rpx; height: 80rpx; line-height: 80rpx; background-color: #07c160; color: #fff; border-radius: 40rpx; font-size: 28rpx; }文件pages/index/index.jsPage({ data: { messages: [], inputValue: , userInfo: {} }, onLoad() { // 获取本地缓存中的消息 const messages wx.getStorageSync(messages) || []; const userInfo wx.getStorageSync(userInfo) || {}; this.setData({ messages, userInfo }); }, onInput(e) { this.setData({ inputValue: e.detail.value }); }, sendMessage() { const content this.data.inputValue.trim(); if (!content) return; const userMessage { role: user, content: content, time: Date.now() }; const messages [...this.data.messages, userMessage]; this.setData({ messages: messages, inputValue: }); // 保存到本地缓存 wx.setStorageSync(messages, messages); // 模拟 AI 回复实际项目中应调用 AI 接口 setTimeout(() { const aiMessage { role: ai, content: 这是一个模拟回复真实回复需要接入 AI 接口。, time: Date.now() }; const newMessages [...this.data.messages, aiMessage]; this.setData({ messages: newMessages }); wx.setStorageSync(messages, newMessages); }, 1000); } });文件pages/index/index.json{ usingComponents: {} }文件pages/user/user.wxmlview classcontainer view classuser-card image classavatar src{{userInfo.avatarUrl || /images/default-avatar.png}} modeaspectFill/image text classnickname{{userInfo.nickName || 未登录}}/text button classlogin-btn bindtapgetUserProfile wx:if{{!userInfo.nickName}}获取用户信息/button button classclear-btn bindtapclearHistory清除聊天记录/button /view /view文件pages/user/user.jsPage({ data: { userInfo: {} }, onLoad() { const userInfo wx.getStorageSync(userInfo) || {}; this.setData({ userInfo }); }, getUserProfile() { wx.getUserProfile({ desc: 用于展示用户信息, success: (res) { const userInfo res.userInfo; wx.setStorageSync(userInfo, userInfo); this.setData({ userInfo }); }, fail: () { wx.showToast({ title: 获取用户信息失败, icon: none }); } }); }, clearHistory() { wx.showModal({ title: 提示, content: 确定要清除所有聊天记录吗, success: (res) { if (res.confirm) { wx.removeStorageSync(messages); wx.showToast({ title: 已清除 }); } } }); } });文件pages/user/user.json{ usingComponents: {} }文件project.config.json部分内容{ description: 项目配置文件, packOptions: { ignore: [], include: [] }, setting: { bundle: false, userConfirmedBundleSwitch: false, urlCheck: true, scopeDataCheck: false, coverView: true, es6: true, postcss: true, compileHotReLoad: false, lazyloadPlaceholderEnable: false, preloadBackgroundData: false, minified: true, autoAudits: false, newFeature: false, uglifyFileName: false, uploadWithSourceMap: true, useIsolateContext: true, nodeModules: false, enhance: true, useMultiFrameRuntime: true, useApiHook: true, useApiHostProcess: true, showShadowRootInWxmlPanel: true, packNpmManually: false, enableEngp: false, packNpmRelationList: [], minifyWXSS: true, showES6CompileOption: false, minifyWXML: true, babelSetting: { ignore: [], disablePlugins: [], outputPath: } }, compileType: miniprogram, libVersion: 3.4.0, appid: 你的AppID, projectname: ai-chat-helper, condition: {}, editorSetting: { tabIndent: insertSpaces, tabSize: 2 } }4.3 第二步创建项目并导入代码在电脑上创建一个文件夹命名为ai-chat-helper。在文件夹内创建上述所有文件并确保文件路径与app.json中配置的pages路径一致。使用微信开发者工具点击“导入项目”选择ai-chat-helper文件夹填入你的 AppID。点击“确定”开发者工具会自动加载项目。4.4 第三步运行与验证首次运行现象点击“编译”按钮开发者工具会显示首页聊天界面。输入框可以输入文字点击“发送”按钮消息会出现在列表中同时显示用户头像和昵称如果已获取用户信息。点击右上角导航栏的“用户”按钮需要手动添加一个跳转入口或者直接在app.json中配置 tabBar这里我们简化处理跳转到用户页。用户页点击“获取用户信息”按钮会弹出授权窗口授权后显示昵称和头像。再次打开小程序聊天记录仍然存在。遇到问题时的排查思路问题现象常见原因解决思路页面空白控制台报错Page is not found页面路径配置错误或文件缺失检查app.json中pages路径是否与文件夹名一致点击发送按钮没有反应事件绑定名称错误或sendMessage函数未定义检查index.wxml中的bindtap与index.js中的函数名是否一致获取用户信息失败未在app.json中配置requiredPrivateInfos或用户拒绝授权引导用户重新授权或使用wx.login降级方案聊天记录不保存wx.setStorageSync调用失败或存储空间不足检查本地存储大小限制单个 key 不超过 1MB消息列表不滚动到底部未在添加消息后执行scroll-into-view在消息列表容器上添加scroll-into-view属性并绑定到最新消息的 id4.5 代码解读与优化建议解读为什么 AI 给出的代码中使用了wx.getUserProfile而不是wx.getUserInfo在微信小程序早期版本中获取用户信息使用wx.getUserInfo接口但该接口在基础库 2.10.4 之后逐渐废弃改为强制使用wx.getUserProfile接口且必须用户主动点击按钮触发。AI 生成的代码正确使用了最新接口这是 AI 训练数据中包含了最新微信文档的结果。优化建议将 AI 模拟回复改为真实接口调用AI 生成的代码中发送消息后使用了一个setTimeout模拟 AI 回复。在实际项目中你需要替换为真实的 AI 接口调用。例如使用微信云开发或后端部署的 AI 模型服务。修改sendMessage函数如下sendMessage() { const content this.data.inputValue.trim(); if (!content) return; const userMessage { role: user, content: content, time: Date.now() }; const messages [...this.data.messages, userMessage]; this.setData({ messages: messages, inputValue: }); wx.setStorageSync(messages, messages); // 调用真实 AI 接口 wx.request({ url: https://your-ai-api.com/chat, method: POST, data: { query: content }, success: (res) { const aiMessage { role: ai, content: res.data.reply, time: Date.now() }; const newMessages [...this.data.messages, aiMessage]; this.setData({ messages: newMessages }); wx.setStorageSync(messages, newMessages); }, fail: (err) { wx.showToast({ title: AI 回复失败, icon: none }); } }); }5. 常见问题与排查思路在 AI 辅助开发微信小程序的过程中最常见的错误集中在以下几个方面。下面整理了一份详细的排查清单你可以直接参考。5.1 项目初始化阶段问题现象常见原因解决思路开发者工具导入项目后报错app.json 文件内容错误JSON 格式错误如多了一个逗号、引号不匹配使用 JSON 格式化工具检查app.json文件内容页面跳转失败报错Pagepages/xxx/xxxis not found页面路径写错或文件夹不存在检查app.json中的路径是否与实际文件夹名一致大小写敏感自定义导航栏不生效未在app.json或对应页面的json中设置navigationStyle: custom在需要自定义导航栏的页面json中添加该配置编译时报错USE_ASM或es6相关开发者工具设置中es6转es5未开启在project.config.json或工具设置中开启es6转码5.2 用户授权与登录问题现象常见原因解决思路点击获取用户信息按钮后无反应按钮未绑定事件或wx.getUserProfile被微信限制检查按钮的bindtap属性确认事件名正确确保小程序已通过审核个人版在正式环境可能被限制获取用户信息后昵称显示为“微信用户”微信对用户昵称做了脱敏处理这是正常现象微信在 2021 年之后返回的userInfo.nickName默认为“微信用户”如需真实昵称需使用wx.login结合后端解密登录后 session_key 过期导致无法获取用户信息未正确处理登录态刷新使用wx.checkSession检查登录态过期时重新调用wx.login获取手机号失败个人小程序不支持获取手机号或未配置button open-typegetPhoneNumber个人开发者无法使用该功能企业开发者需确保按钮属性正确5.3 数据存储与缓存问题现象常见原因解决思路缓存数据无法保存存储空间不足单个 key 不可超过 1MB总空间不可超过 10MB检查缓存数据大小考虑使用wx.setStorage异步接口并捕获异常缓存数据读取后与预期不符存储时使用了JSON.stringify后的字符串读取时未做JSON.parse使用wx.setStorageSync和wx.getStorageSync时数据会自动序列化/反序列化无需手动处理多个页面共享缓存数据不一致未在页面onShow中刷新数据在onShow生命周期中重新读取缓存并更新页面数据清除缓存后页面未刷新清除数据后未调用setData更新页面在清除缓存后手动调用setData清空页面数据或重置状态5.4 网络请求与后端调用问题现象常见原因解决思路请求被拒绝报错request:fail请求的 URL 未在微信公众平台配置合法域名或在开发者工具中未关闭域名校验在开发者工具中勾选“不校验合法域名”或到微信公众平台添加合法域名请求超时后端接口响应慢或网络不稳定设置合理的timeout参数默认 60s并在前端做好 loading 状态和超时提示返回数据格式异常后端返回的数据不是 JSON 格式或字段名不匹配在success回调中先打印res.data确认格式再使用typeof判断类型跨域问题小程序不存在跨域问题但后端需要正确处理 CORS 头小程序请求天然不受浏览器同源策略限制但如果后端返回了非 200 状态码需要后端配合调整5.5 页面渲染与样式问题现象常见原因解决思路页面布局错乱使用了不支持的 CSS 属性或单位微信小程序不支持flex的某些属性如gap在低版本基础库中不支持建议使用margin或padding替代字体大小异常未使用rpx单位微信小程序中不同屏幕宽度需使用rpx实现自适应px会导致字体大小固定图片无法显示图片路径错误或未上传到 CDN检查图片路径是否以/开头绝对路径或相对路径正确网络图片需配置合法域名滚动条消失在scroll-view中设置了scroll-y但未指定高度scroll-view必须指定固定高度或通过flex布局撑开否则无法滚动6. 最佳实践与工程建议6.1 与 AI 协作的高效模式模式一分步生成逐步验证不要一次性让 AI 生成整个项目。建议按以下顺序分步生成生成项目骨架app.json、project.config.json。生成首页页面wxml wxss js json。生成用户页页面。生成数据缓存逻辑。生成网络请求与 AI 接口调用。生成错误处理与加载状态。每生成一步就在开发者工具中编译一次确认无误后再进行下一步。这样即使某一环节出错也能快速定位。模式二使用“示例-需求”模式如果你对 AI 的生成结果不满意可以给 AI 提供已有的示例代码然后要求它基于示例修改。例如“参考以下代码帮我实现一个类似的功能但将数据源从本地缓存改为从云数据库读取 [粘贴示例代码] 需求在用户页展示用户的聊天记录总数并显示最近一条消息的时间。”模式三结合 AI 进行代码审查AI 不仅能生成代码还能审查代码。当你写完一段代码后可以把它丢给 AI让它帮你检查潜在的问题“请审查以下微信小程序代码找出可能存在的安全隐患和性能问题 [粘贴代码]”AI 通常能发现资源未释放、空指针、异常未捕获、代码冗余等问题。6.2 微信小程序开发规范命名规范页面文件夹名使用小写字母多个单词用-连接如user-profile。页面文件内的四个文件wxml、wxss、js、json使用相同的文件名保持与文件夹名一致。变量名使用驼峰命名如userInfo、messageList。HTML 标签使用全小写属性使用kebab-case如bindtap、>
1. 背景与核心概念1.1 什么是 Skill一个全新的 AI 开发范式在传统的软件开发流程中从需求分析、原型设计、UI 开发、后端联调、测试到最终部署上线往往需要多个角色、多轮迭代、多套工具配合才能完成一个最小可用产品。对于微信小程序这种前端与后端、移动端与微信生态深度耦合的场景技术栈杂、坑点多、调试流程长很多开发者尤其是个人开发者或小团队常常在环境配置和基础功能开发阶段就耗费了大量精力。“Skill” 这个词在最近的技术圈中逐渐被赋予了一个新的定义它不是指游戏里的技能也不是指某个人的专业技能而是一种由 AI 大模型驱动的、可复用的自动化开发能力单元。简单来说你可以把 Skill 理解为一个“AI 开发助手插件”——它能够根据你的自然语言描述理解你的业务需求然后自动生成符合你技术栈的完整代码、配置文件、依赖说明甚至直接帮你搭建好可运行的项目骨架。当 AI 与微信小程序开发结合这个 Skill 就是一整套从“我想做一个什么样的小程序”到“小程序已经能在微信开发者工具中正常跑起来”的完整流程。它不再是简单的代码补全或片段生成而是需求理解、架构设计、代码生成、环境配置、依赖安装、错误修正的全链路自动化。1.2 为什么需要这个 Skill解决开发者的真实痛点在实际开发中微信小程序入门并不难但要做到“从零到首次运行”中间有大量重复性工作和技术细节项目初始化繁琐每次新建项目都要配置 appid、域名白名单、合法域名、SSL 证书等。页面与组件结构重复每个页面都要写 wxml、wxss、js、json 四个文件且逻辑相似。API 调用与权限处理用户登录、获取手机号、接口超时、数据缓存等每个点都可能踩坑。版本兼容与适配微信基础库版本、iPhone 刘海屏适配、自定义导航栏高度等。调试与测试成本高真机调试、预览、上传代码每个环节都可能出现不可预期的问题。而 AI 开发 Skill 正是为了解决这些问题而生。它能够理解你的自然语言需求你说“我要做一个 AI 心理咨询助手小程序”它能自动拆解出核心功能模块。生成最小可行代码包括页面、组件、API 调用、数据管理等。自动处理依赖与配置安装 npm 包、配置 webpack、设置合法域名等。提供实时调试建议遇到报错时能根据错误信息给出修复方案。1.3 适用读者与学完后的收获本文适合以下读者群体微信小程序初学者想快速跑通一个完整的小程序而不是卡在环境配置上。全栈开发者希望能用 AI 加速日常开发流程减少重复劳动。产品经理或创业者想快速验证自己的想法看到可用的 Demo 再决定是否投入完整开发。AI 开发爱好者对 AI 编程、大模型落地实践感兴趣想了解最新的开发范式。学完本文后你将能够掌握使用 AI 开发 Skill 完成微信小程序从需求分析到首次运行的完整流程。理解 AI 生成代码的常见模式与局限性知道如何高效地与 AI 协作。独立完成一个包含用户登录、数据展示、页面跳转等核心功能的小程序初始版本。掌握微信小程序开发中的常见坑点和最佳实践避免重复踩坑。2. 环境准备与版本说明2.1 开发环境要求在开始之前请确保你的电脑满足以下基础环境要求。版本号以本文撰写时的常见稳定版本为准实际开发中请根据项目需求灵活调整。项目推荐版本说明操作系统Windows 10 / macOS 12 / Linux Ubuntu 20.04主流系统均可建议 64 位Node.js18.x LTS 或 20.x LTS用于构建工具和 npm 包管理微信开发者工具最新稳定版 1.06.xxx下载地址微信公众平台官网微信小程序 AppID已注册的小程序 AppID未注册可到 mp.weixin.qq.com 注册代码编辑器VS Code 微信开发者工具VS Code 推荐安装 ESLint、Prettier、vscode-wechatAI 开发平台支持自然语言生成代码的 AI 平台如 OpenAI API、Claude API、文心一言等按需选择2.2 注册与准备工作第一步注册微信小程序账号如果你还没有微信小程序账号需要先到 微信公众平台 完成注册。注册流程如下点击“立即注册”选择“小程序”。填写邮箱、密码、验证码完成邮箱激活。选择主体类型个人、企业、媒体等个人开发者建议选择“个人”。完善小程序信息包括名称、头像、介绍等。注册成功后进入“开发” - “开发设置”获取你的 AppID。注意AppID 是微信小程序的身份标识后续所有开发环节都需要用到。个人开发者申请的 AppID 部分权限受限如支付、附近的小程序等但开发学习完全够用。第二步下载并安装微信开发者工具微信开发者工具是官方提供的集成开发环境支持代码编辑、调试、预览、上传等功能。请到微信公众平台下载对应你操作系统的最新版本。安装完成后用微信扫码登录即可。第三步准备 AI 开发 Skill 环境AI 开发 Skill 的使用方式有很多种本文采用以下通用方案使用支持大模型 API 调用的开发环境如 Python 环境 OpenAI 库。或者使用 AI 编程助手插件如 Cursor、Codex、GitHub Copilot 等。或者使用支持自然语言交互的网页版 AI 平台如 ChatGPT、Claude 等。本文以“使用 API 调用 AI 模型生成代码”为例你可以在本地创建一个 Python 脚本调用 AI 接口生成小程序代码。如果你对 Python 不熟悉也可以直接使用 AI 聊天界面手动将生成的代码复制到项目中。2.3 项目结构规划在开始生成代码之前我们先规划一下微信小程序的标准项目结构。一个典型的微信小程序项目根目录下包含以下文件和文件夹mini-program-demo/ ├── app.js # 小程序全局逻辑 ├── app.json # 小程序全局配置 ├── app.wxss # 小程序全局样式 ├── project.config.json # 项目配置文件开发者工具读 ├── pages/ # 页面文件夹 │ ├── index/ # 首页 │ │ ├── index.js │ │ ├── index.json │ │ ├── index.wxml │ │ └── index.wxss │ └── logs/ # 日志页 │ ├── logs.js │ ├── logs.json │ ├── logs.wxml │ └── logs.wxss ├── utils/ # 工具函数 │ └── util.js ├── images/ # 图片资源 └── style/ # 公共样式这个结构是微信小程序的基础骨架后续所有页面、组件、API 调用都会在此基础上扩展。AI 生成代码时也会遵循这个结构来组织文件。3. 核心原理拆解AI 如何理解需求并生成小程序代码3.1 AI 理解需求的流程AI 开发 Skill 的核心能力是“自然语言转代码”。它并不是真正理解你的业务而是通过大量的训练数据学会了从文本描述到代码输出的映射关系。当你说“我想做一个 AI 心理咨询助手小程序”时AI 内部大致会经历以下四个步骤意图识别解析输入文本找出核心关键词如“AI”、“心理咨询”、“小程序”、“助手”。功能拆解基于常见的微信小程序功能模式拆解出协议所需的功能模块比如用户登录与授权获取用户信息首页展示聊天界面或咨询入口对话功能输入框 消息列表数据存储本地缓存或云开发数据库技术选型根据功能模块选择合适的技术方案。例如用户登录优先使用 wx.login 后端接口数据存储使用本地缓存或微信云开发数据库。代码生成按照微信小程序的开发规范生成对应的文件结构、配置文件、页面代码、API 调用代码。3.2 AI 生成代码的常见模式模式一生成完整项目骨架这种模式最适合“从零开始搭建项目”。你只需要输入需求描述AI 就会一次性生成整个 project 的所有文件。例如用户输入帮我生成一个微信小程序项目首页是一个聊天界面包含一个输入框和一个发送按钮点击发送后消息显示在列表中。AI 会生成app.json配置页面路径、窗口样式、tabBar 等。pages/index/index.wxml聊天界面模板。pages/index/index.wxss聊天界面样式。pages/index/index.js输入框事件、发送逻辑、消息列表渲染。pages/index/index.json页面配置。模式二生成特定功能模块这种模式适合在已有项目基础上添加新功能。例如用户输入在现有项目的 pages/user 页面上添加一个“获取用户手机号”的按钮点击后调用微信 API 获取手机号并保存到本地缓存。AI 会生成以pages/user文件夹为目标的修改后代码并提示你需要在app.json中注册该页面如果尚未注册。模式三生成 API 调用与数据处理逻辑这种模式适合后端接口联调或数据展示。例如用户输入写一个微信小程序页面用于展示一个文章列表通过 wx.request 调用 GET 接口 https://api.example.com/articles 获取数据并在页面渲染。AI 会生成完整的页面代码包括 loading 状态、错误处理、列表渲染、下拉刷新等。3.3 AI 辅助开发的核心原则可控与可解释虽然 AI 生成代码的能力越来越强但你不能完全依赖它。以下是几个核心原则能帮助你更好地与 AI 协作先拆解再生成在给 AI 输入需求之前自己先拆解一下功能模块。拆解得越细AI 生成的代码越精准。分步生成逐步验证不要一次性让 AI 生成整个项目这样容易出错且难以调试。建议先让 AI 生成项目骨架跑通后再生成页面最后生成逻辑。理解代码而非盲复制AI 生成的代码不一定是最优的甚至可能有 bug。你需要理解每一行代码的作用尤其是 API 调用和权限处理部分。保留人工审核环节涉及用户数据、支付、敏感信息的功能必须由人工审核代码安全性不能直接上线。4. 完整实战案例用 AI 开发一个“AI 心理咨询助手”小程序4.1 需求描述我们希望开发一个微信小程序核心功能如下首页显示一个简单的聊天界面包含一个消息列表和一个输入框。用户在输入框中输入文字点击“发送”按钮消息出现在列表中。实现用户登录功能获取用户的昵称和头像并显示在聊天界面的右上角。使用本地缓存保存聊天记录下次打开小程序时还能看到历史消息。页面样式简洁类似微信聊天界面。4.2 第一步让 AI 生成项目骨架首先我们向 AI 输入以下需求请帮我生成一个微信小程序项目骨架命名为 ai-chat-helper。要求 - 项目包含两个页面首页index和用户页user。 - 首页是聊天界面包含消息列表和输入框。 - 用户页用于显示用户信息昵称、头像。 - 全局配置app.json中设置窗口背景色为白色导航栏标题为AI 心理助手。 - 不需要tabBar。 - 不需要网络请求所有数据存本地缓存。AI 会生成以下文件以 OpenAI 的 ChatGPT 或 Claude 为例实际输出可能略有差异但核心逻辑一致文件app.json{ pages: [ pages/index/index, pages/user/user ], window: { navigationBarTitleText: AI 心理助手, navigationBarBackgroundColor: #ffffff, navigationBarTextStyle: black, backgroundColor: #ffffff }, sitemapLocation: sitemap.json }文件pages/index/index.wxmlview classcontainer view classmessage-list view wx:for{{messages}} wx:keyindex classmessage-item {{item.role user ? user : ai}} view classavatar image src{{item.role user ? userInfo.avatarUrl : /images/ai-avatar.png}} modeaspectFill/image /view view classbubble{{item.content}}/view /view /view view classinput-area input classinput typetext placeholder输入你的问题... bindinputonInput value{{inputValue}} / button classsend-btn bindtapsendMessage发送/button /view /view文件pages/index/index.wxss.container { display: flex; flex-direction: column; height: 100vh; } .message-list { flex: 1; overflow-y: auto; padding: 20rpx; } .message-item { display: flex; margin-bottom: 30rpx; } .message-item.user { flex-direction: row-reverse; } .avatar { width: 80rpx; height: 80rpx; border-radius: 50%; overflow: hidden; margin: 0 20rpx; } .avatar image { width: 100%; height: 100%; } .bubble { max-width: 60%; padding: 20rpx 30rpx; border-radius: 20rpx; background-color: #f0f0f0; font-size: 28rpx; line-height: 1.5; } .message-item.user .bubble { background-color: #95ec69; } .input-area { display: flex; padding: 20rpx; border-top: 1px solid #eee; align-items: center; } .input { flex: 1; height: 80rpx; border: 1px solid #ddd; border-radius: 40rpx; padding: 0 30rpx; font-size: 28rpx; } .send-btn { margin-left: 20rpx; padding: 0 40rpx; height: 80rpx; line-height: 80rpx; background-color: #07c160; color: #fff; border-radius: 40rpx; font-size: 28rpx; }文件pages/index/index.jsPage({ data: { messages: [], inputValue: , userInfo: {} }, onLoad() { // 获取本地缓存中的消息 const messages wx.getStorageSync(messages) || []; const userInfo wx.getStorageSync(userInfo) || {}; this.setData({ messages, userInfo }); }, onInput(e) { this.setData({ inputValue: e.detail.value }); }, sendMessage() { const content this.data.inputValue.trim(); if (!content) return; const userMessage { role: user, content: content, time: Date.now() }; const messages [...this.data.messages, userMessage]; this.setData({ messages: messages, inputValue: }); // 保存到本地缓存 wx.setStorageSync(messages, messages); // 模拟 AI 回复实际项目中应调用 AI 接口 setTimeout(() { const aiMessage { role: ai, content: 这是一个模拟回复真实回复需要接入 AI 接口。, time: Date.now() }; const newMessages [...this.data.messages, aiMessage]; this.setData({ messages: newMessages }); wx.setStorageSync(messages, newMessages); }, 1000); } });文件pages/index/index.json{ usingComponents: {} }文件pages/user/user.wxmlview classcontainer view classuser-card image classavatar src{{userInfo.avatarUrl || /images/default-avatar.png}} modeaspectFill/image text classnickname{{userInfo.nickName || 未登录}}/text button classlogin-btn bindtapgetUserProfile wx:if{{!userInfo.nickName}}获取用户信息/button button classclear-btn bindtapclearHistory清除聊天记录/button /view /view文件pages/user/user.jsPage({ data: { userInfo: {} }, onLoad() { const userInfo wx.getStorageSync(userInfo) || {}; this.setData({ userInfo }); }, getUserProfile() { wx.getUserProfile({ desc: 用于展示用户信息, success: (res) { const userInfo res.userInfo; wx.setStorageSync(userInfo, userInfo); this.setData({ userInfo }); }, fail: () { wx.showToast({ title: 获取用户信息失败, icon: none }); } }); }, clearHistory() { wx.showModal({ title: 提示, content: 确定要清除所有聊天记录吗, success: (res) { if (res.confirm) { wx.removeStorageSync(messages); wx.showToast({ title: 已清除 }); } } }); } });文件pages/user/user.json{ usingComponents: {} }文件project.config.json部分内容{ description: 项目配置文件, packOptions: { ignore: [], include: [] }, setting: { bundle: false, userConfirmedBundleSwitch: false, urlCheck: true, scopeDataCheck: false, coverView: true, es6: true, postcss: true, compileHotReLoad: false, lazyloadPlaceholderEnable: false, preloadBackgroundData: false, minified: true, autoAudits: false, newFeature: false, uglifyFileName: false, uploadWithSourceMap: true, useIsolateContext: true, nodeModules: false, enhance: true, useMultiFrameRuntime: true, useApiHook: true, useApiHostProcess: true, showShadowRootInWxmlPanel: true, packNpmManually: false, enableEngp: false, packNpmRelationList: [], minifyWXSS: true, showES6CompileOption: false, minifyWXML: true, babelSetting: { ignore: [], disablePlugins: [], outputPath: } }, compileType: miniprogram, libVersion: 3.4.0, appid: 你的AppID, projectname: ai-chat-helper, condition: {}, editorSetting: { tabIndent: insertSpaces, tabSize: 2 } }4.3 第二步创建项目并导入代码在电脑上创建一个文件夹命名为ai-chat-helper。在文件夹内创建上述所有文件并确保文件路径与app.json中配置的pages路径一致。使用微信开发者工具点击“导入项目”选择ai-chat-helper文件夹填入你的 AppID。点击“确定”开发者工具会自动加载项目。4.4 第三步运行与验证首次运行现象点击“编译”按钮开发者工具会显示首页聊天界面。输入框可以输入文字点击“发送”按钮消息会出现在列表中同时显示用户头像和昵称如果已获取用户信息。点击右上角导航栏的“用户”按钮需要手动添加一个跳转入口或者直接在app.json中配置 tabBar这里我们简化处理跳转到用户页。用户页点击“获取用户信息”按钮会弹出授权窗口授权后显示昵称和头像。再次打开小程序聊天记录仍然存在。遇到问题时的排查思路问题现象常见原因解决思路页面空白控制台报错Page is not found页面路径配置错误或文件缺失检查app.json中pages路径是否与文件夹名一致点击发送按钮没有反应事件绑定名称错误或sendMessage函数未定义检查index.wxml中的bindtap与index.js中的函数名是否一致获取用户信息失败未在app.json中配置requiredPrivateInfos或用户拒绝授权引导用户重新授权或使用wx.login降级方案聊天记录不保存wx.setStorageSync调用失败或存储空间不足检查本地存储大小限制单个 key 不超过 1MB消息列表不滚动到底部未在添加消息后执行scroll-into-view在消息列表容器上添加scroll-into-view属性并绑定到最新消息的 id4.5 代码解读与优化建议解读为什么 AI 给出的代码中使用了wx.getUserProfile而不是wx.getUserInfo在微信小程序早期版本中获取用户信息使用wx.getUserInfo接口但该接口在基础库 2.10.4 之后逐渐废弃改为强制使用wx.getUserProfile接口且必须用户主动点击按钮触发。AI 生成的代码正确使用了最新接口这是 AI 训练数据中包含了最新微信文档的结果。优化建议将 AI 模拟回复改为真实接口调用AI 生成的代码中发送消息后使用了一个setTimeout模拟 AI 回复。在实际项目中你需要替换为真实的 AI 接口调用。例如使用微信云开发或后端部署的 AI 模型服务。修改sendMessage函数如下sendMessage() { const content this.data.inputValue.trim(); if (!content) return; const userMessage { role: user, content: content, time: Date.now() }; const messages [...this.data.messages, userMessage]; this.setData({ messages: messages, inputValue: }); wx.setStorageSync(messages, messages); // 调用真实 AI 接口 wx.request({ url: https://your-ai-api.com/chat, method: POST, data: { query: content }, success: (res) { const aiMessage { role: ai, content: res.data.reply, time: Date.now() }; const newMessages [...this.data.messages, aiMessage]; this.setData({ messages: newMessages }); wx.setStorageSync(messages, newMessages); }, fail: (err) { wx.showToast({ title: AI 回复失败, icon: none }); } }); }5. 常见问题与排查思路在 AI 辅助开发微信小程序的过程中最常见的错误集中在以下几个方面。下面整理了一份详细的排查清单你可以直接参考。5.1 项目初始化阶段问题现象常见原因解决思路开发者工具导入项目后报错app.json 文件内容错误JSON 格式错误如多了一个逗号、引号不匹配使用 JSON 格式化工具检查app.json文件内容页面跳转失败报错Pagepages/xxx/xxxis not found页面路径写错或文件夹不存在检查app.json中的路径是否与实际文件夹名一致大小写敏感自定义导航栏不生效未在app.json或对应页面的json中设置navigationStyle: custom在需要自定义导航栏的页面json中添加该配置编译时报错USE_ASM或es6相关开发者工具设置中es6转es5未开启在project.config.json或工具设置中开启es6转码5.2 用户授权与登录问题现象常见原因解决思路点击获取用户信息按钮后无反应按钮未绑定事件或wx.getUserProfile被微信限制检查按钮的bindtap属性确认事件名正确确保小程序已通过审核个人版在正式环境可能被限制获取用户信息后昵称显示为“微信用户”微信对用户昵称做了脱敏处理这是正常现象微信在 2021 年之后返回的userInfo.nickName默认为“微信用户”如需真实昵称需使用wx.login结合后端解密登录后 session_key 过期导致无法获取用户信息未正确处理登录态刷新使用wx.checkSession检查登录态过期时重新调用wx.login获取手机号失败个人小程序不支持获取手机号或未配置button open-typegetPhoneNumber个人开发者无法使用该功能企业开发者需确保按钮属性正确5.3 数据存储与缓存问题现象常见原因解决思路缓存数据无法保存存储空间不足单个 key 不可超过 1MB总空间不可超过 10MB检查缓存数据大小考虑使用wx.setStorage异步接口并捕获异常缓存数据读取后与预期不符存储时使用了JSON.stringify后的字符串读取时未做JSON.parse使用wx.setStorageSync和wx.getStorageSync时数据会自动序列化/反序列化无需手动处理多个页面共享缓存数据不一致未在页面onShow中刷新数据在onShow生命周期中重新读取缓存并更新页面数据清除缓存后页面未刷新清除数据后未调用setData更新页面在清除缓存后手动调用setData清空页面数据或重置状态5.4 网络请求与后端调用问题现象常见原因解决思路请求被拒绝报错request:fail请求的 URL 未在微信公众平台配置合法域名或在开发者工具中未关闭域名校验在开发者工具中勾选“不校验合法域名”或到微信公众平台添加合法域名请求超时后端接口响应慢或网络不稳定设置合理的timeout参数默认 60s并在前端做好 loading 状态和超时提示返回数据格式异常后端返回的数据不是 JSON 格式或字段名不匹配在success回调中先打印res.data确认格式再使用typeof判断类型跨域问题小程序不存在跨域问题但后端需要正确处理 CORS 头小程序请求天然不受浏览器同源策略限制但如果后端返回了非 200 状态码需要后端配合调整5.5 页面渲染与样式问题现象常见原因解决思路页面布局错乱使用了不支持的 CSS 属性或单位微信小程序不支持flex的某些属性如gap在低版本基础库中不支持建议使用margin或padding替代字体大小异常未使用rpx单位微信小程序中不同屏幕宽度需使用rpx实现自适应px会导致字体大小固定图片无法显示图片路径错误或未上传到 CDN检查图片路径是否以/开头绝对路径或相对路径正确网络图片需配置合法域名滚动条消失在scroll-view中设置了scroll-y但未指定高度scroll-view必须指定固定高度或通过flex布局撑开否则无法滚动6. 最佳实践与工程建议6.1 与 AI 协作的高效模式模式一分步生成逐步验证不要一次性让 AI 生成整个项目。建议按以下顺序分步生成生成项目骨架app.json、project.config.json。生成首页页面wxml wxss js json。生成用户页页面。生成数据缓存逻辑。生成网络请求与 AI 接口调用。生成错误处理与加载状态。每生成一步就在开发者工具中编译一次确认无误后再进行下一步。这样即使某一环节出错也能快速定位。模式二使用“示例-需求”模式如果你对 AI 的生成结果不满意可以给 AI 提供已有的示例代码然后要求它基于示例修改。例如“参考以下代码帮我实现一个类似的功能但将数据源从本地缓存改为从云数据库读取 [粘贴示例代码] 需求在用户页展示用户的聊天记录总数并显示最近一条消息的时间。”模式三结合 AI 进行代码审查AI 不仅能生成代码还能审查代码。当你写完一段代码后可以把它丢给 AI让它帮你检查潜在的问题“请审查以下微信小程序代码找出可能存在的安全隐患和性能问题 [粘贴代码]”AI 通常能发现资源未释放、空指针、异常未捕获、代码冗余等问题。6.2 微信小程序开发规范命名规范页面文件夹名使用小写字母多个单词用-连接如user-profile。页面文件内的四个文件wxml、wxss、js、json使用相同的文件名保持与文件夹名一致。变量名使用驼峰命名如userInfo、messageList。HTML 标签使用全小写属性使用kebab-case如bindtap、>
