miniprogram-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to use this skill

何时使用本技能

Use this skill for WeChat Mini Program development when you need to:
  • Develop WeChat mini program pages and components
  • Integrate CloudBase capabilities (database, cloud functions, storage)
  • Deploy and preview mini program projects
  • Handle mini program authentication and user identity
  • Call AI models in mini programs
  • Get WeChat step count data
Do NOT use for:
  • Web frontend development (use web-development skill)
  • Backend service development (use cloudrun-development skill)
  • UI design only (use ui-design skill, but may combine with this skill)

当你需要进行以下操作时,可使用本技能进行微信小程序开发
  • 开发微信小程序页面与组件
  • 集成CloudBase能力(数据库、云函数、存储)
  • 部署与预览小程序项目
  • 处理小程序认证与用户身份
  • 在小程序中调用AI模型
  • 获取微信步数数据
请勿用于:
  • Web前端开发(使用web-development技能)
  • 后端服务开发(使用cloudrun-development技能)
  • 仅UI设计(使用ui-design技能,但可与本技能结合使用)

How to use this skill (for a coding agent)

如何使用本技能(面向编码Agent)

  1. Follow project structure conventions
    • Mini program code in
      miniprogram
      directory
    • Cloud functions in
      cloudfunctions
      directory
    • Use latest base library version
    • Include page configuration files (e.g., index.json) when generating pages
  2. Understand authentication characteristics
    • Important: Mini programs with CloudBase are naturally login-free
    • Never generate login pages or login flows
    • Get user identity via
      cloud.getWXContext().OPENID
      in cloud functions
  3. Use WeChat Developer Tools correctly
    • Check
      project.config.json
      has
      appid
      field before opening
    • Use CLI command to open project pointing to directory containing
      project.config.json
  4. Handle resources properly
    • Icons8 (Recommended): Use Icons8 for icon images (e.g., tabbar iconPath)
      • URL format:
        https://img.icons8.com/{style}/{size}/{color}/{icon-name}.png
      • Parameters:
        • style
          :
          ios
          (outline style) or
          ios-filled
          (filled style)
        • size
          :
          100
          (recommended 100px, file size < 5KB)
        • color
          : hex color code without # (e.g.,
          8E8E93
          for gray,
          FF3B30
          for red)
        • icon-name
          : icon name (e.g.,
          checked--v1
          )
      • Examples:
        • Unselected (gray outline):
          https://img.icons8.com/ios/100/8E8E93/checked--v1.png
        • Selected (red filled):
          https://img.icons8.com/ios-filled/100/FF3B30/checked--v1.png
      • Advantages:
        • ✅ Very small file size (usually < 3KB)
        • ✅ Supports custom colors
        • ✅ Clean and professional icons
    • Use
      downloadRemoteFile
      tool to download resources
    • Avoid build errors by ensuring all referenced resources exist

  1. 遵循项目结构规范
    • 小程序代码存放于
      miniprogram
      目录
    • 云函数存放于
      cloudfunctions
      目录
    • 使用最新基础库版本
    • 生成页面时需包含页面配置文件(如index.json)
  2. 了解认证特性
    • 重要提示:集成CloudBase的小程序天然免登录
    • 禁止生成登录页面或登录流程
    • 在云函数中通过
      cloud.getWXContext().OPENID
      获取用户身份
  3. 正确使用WeChat Developer Tools
    • 打开前检查
      project.config.json
      是否包含
      appid
      字段
    • 使用CLI命令打开指向包含
      project.config.json
      的目录的项目
  4. 合理处理资源
    • Icons8(推荐):使用Icons8获取图标图片(如tabbar的iconPath)
      • URL格式:
        https://img.icons8.com/{style}/{size}/{color}/{icon-name}.png
      • 参数说明:
        • style
          ios
          (轮廓样式)或
          ios-filled
          (填充样式)
        • size
          100
          (推荐100px,文件大小<5KB)
        • color
          :不带#的十六进制颜色码(如灰色
          8E8E93
          ,红色
          FF3B30
        • icon-name
          :图标名称(如
          checked--v1
      • 示例:
        • 未选中(灰色轮廓):
          https://img.icons8.com/ios/100/8E8E93/checked--v1.png
        • 选中(红色填充):
          https://img.icons8.com/ios-filled/100/FF3B30/checked--v1.png
      • 优势:
        • ✅ 文件体积极小(通常<3KB)
        • ✅ 支持自定义颜色
        • ✅ 图标简洁专业
    • 使用
      downloadRemoteFile
      工具下载资源
    • 确保所有引用的资源存在,以避免构建错误

WeChat Mini Program Development Rules

微信小程序开发规则

Project Structure

项目结构

  1. CloudBase Integration:
    • If user needs to develop mini program, you will use various WeChat CloudBase capabilities to develop the project
    • Mini program base library should use
      latest
      version
  2. Directory Organization:
    • Mini program projects follow WeChat CloudBase best practices
    • Mini program code is generally in
      miniprogram
      directory
    • If developing cloud functions, they can be stored in
      cloudfunctions
      directory
    • Mini program's
      project.config.json
      needs to specify
      miniprogramRoot
      and other configurations
  3. Page Generation:
    • When generating mini program pages, must include page configuration files such as
      index.json
    • Must comply with specifications to avoid compilation errors
  1. CloudBase集成
    • 若用户需要开发小程序,需使用各类CloudBase能力进行项目开发
    • 小程序基础库应使用
      latest
      版本
  2. 目录组织
    • 小程序项目遵循CloudBase最佳实践
    • 小程序代码通常存放于
      miniprogram
      目录
    • 若开发云函数,可存放于
      cloudfunctions
      目录
    • 小程序的
      project.config.json
      需指定
      miniprogramRoot
      等配置
  3. 页面生成
    • 生成小程序页面时,必须包含
      index.json
      等页面配置文件
    • 必须符合规范以避免编译错误

Development Tools

开发工具

WeChat Developer Tools Opening Project Workflow:
  • When detecting current project is a mini program project, suggest user to use WeChat Developer Tools for preview, debugging, and publishing
  • Before opening, confirm
    project.config.json
    has
    appid
    field configured. If not configured, must ask user to provide it
  • Use WeChat Developer built-in CLI command to open project (pointing to directory containing
    project.config.json
    ):
    • Windows:
      "C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" open --project "项目根目录路径"
    • macOS:
      /Applications/wechatwebdevtools.app/Contents/MacOS/cli open --project "/path/to/project/root"
  • Project root directory path is the directory containing
    project.config.json
    file
WeChat Developer Tools 打开项目流程
  • 当检测到当前项目为小程序项目时,建议用户使用WeChat Developer Tools进行预览、调试与发布
  • 打开前需确认
    project.config.json
    已配置
    appid
    字段,若未配置,必须要求用户提供
  • 使用WeChat Developer内置的CLI命令打开项目(指向包含
    project.config.json
    的目录):
    • Windows:
      "C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat" open --project "项目根目录路径"
    • macOS:
      /Applications/wechatwebdevtools.app/Contents/MacOS/cli open --project "/path/to/project/root"
  • 项目根目录路径为包含
    project.config.json
    文件的目录

CloudBase Integration

CloudBase集成

  1. Environment Configuration:
    • When using
      wx.cloud
      in mini program, need to specify environment ID
    • Environment ID can be queried via
      envQuery
      tool
  2. Resource Management:
    • When generating mini program code, if material images are needed, such as tabbar's
      iconPath
      and other places, prefer Icons8 (see section 4 above for details)
    • Use
      downloadRemoteFile
      tool to download resources
    • When generating mini program code, if using
      iconPath
      and similar, must simultaneously help user download icons to avoid build errors
  1. 环境配置
    • 在小程序中使用
      wx.cloud
      时,需指定环境ID
    • 环境ID可通过
      envQuery
      工具查询
  2. 资源管理
    • 生成小程序代码时,若需要素材图片(如tabbar的
      iconPath
      等位置),优先使用Icons8(详情见上文第4部分)
    • 使用
      downloadRemoteFile
      工具下载资源
    • 生成小程序代码时,若使用
      iconPath
      等,必须同时帮助用户下载图标以避免构建错误

Mini Program Authentication Characteristics

小程序认证特性

Important: Mini programs with CloudBase are naturally login-free. It is strictly forbidden to generate login pages or login flows!
  1. Login-Free Feature: Mini program CloudBase does not require user login, can get user identity in cloud functions via wx-server-sdk
  2. User Identity Retrieval: In cloud functions, get user's unique identifier via
    cloud.getWXContext().OPENID
  3. User Data Management: Manage user data in cloud functions based on openid, no login flow needed
js
// Example of getting user identity in cloud function
exports.main = async (event, context) => {
  const wxContext = cloud.getWXContext();
  const openid = wxContext.OPENID;
  
  return { openid: openid };
};
重要提示:集成CloudBase的小程序天然免登录,严禁生成登录页面或登录流程!
  1. 免登录特性:小程序CloudBase无需用户登录,可通过wx-server-sdk在云函数中获取用户身份
  2. 用户身份获取:在云函数中,通过
    cloud.getWXContext().OPENID
    获取用户唯一标识
  3. 用户数据管理:基于openid在云函数中管理用户数据,无需登录流程
js
// 云函数中获取用户身份的示例
exports.main = async (event, context) => {
  const wxContext = cloud.getWXContext();
  const openid = wxContext.OPENID;
  
  return { openid: openid };
};

AI Model Invocation

AI模型调用

Mini programs with base library version 3.7.1+ already support direct AI model invocation
js
// Create model instance, here we use DeepSeek AI model
const model = wx.cloud.extend.AI.createModel("deepseek");

// First set AI's system prompt, here using seven-character quatrain generation as example
const systemPrompt =
  "请严格按照七言绝句或七言律诗的格律要求创作,平仄需符合规则,押韵要和谐自然,韵脚字需在同一韵部。创作内容围绕用户给定的主题,七言绝句共四句,每句七个字;七言律诗共八句,每句七个字,颔联和颈联需对仗工整。同时,要融入生动的意象、丰富的情感与优美的意境,展现出古诗词的韵味与美感。";

// User's natural language input, e.g., '帮我写一首赞美玉龙雪山的诗'
const userInput = "帮我写一首赞美玉龙雪山的诗";

// Pass system prompt and user input to AI model
const res = await model.streamText({
  data: {
    model: "deepseek-v3", // Specify specific model
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: userInput },
    ],
  },
});

// Receive AI model's response
// Since AI model's return result is streaming, we need to loop to receive complete response text
for await (let str of res.textStream) {
  console.log(str);
}
基础库版本3.7.1及以上的小程序已支持直接调用AI模型
js
// 创建模型实例,此处使用DeepSeek AI模型
const model = wx.cloud.extend.AI.createModel("deepseek");

// 首先设置AI的系统提示词,此处以七言绝句生成为例
const systemPrompt =
  "请严格按照七言绝句或七言律诗的格律要求创作,平仄需符合规则,押韵要和谐自然,韵脚字需在同一韵部。创作内容围绕用户给定的主题,七言绝句共四句,每句七个字;七言律诗共八句,每句七个字,颔联和颈联需对仗工整。同时,要融入生动的意象、丰富的情感与优美的意境,展现出古诗词的韵味与美感。";

// 用户自然语言输入,例如:'帮我写一首赞美玉龙雪山的诗'
const userInput = "帮我写一首赞美玉龙雪山的诗";

// 将系统提示词和用户输入传入AI模型
const res = await model.streamText({
  data: {
    model: "deepseek-v3", // 指定具体模型
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: userInput },
    ],
  },
});

// 接收AI模型的响应
// 由于AI模型的返回结果为流式,需要循环接收完整响应文本
for await (let str of res.textStream) {
  console.log(str);
}

WeChat Step Count Retrieval

微信步数获取

WeChat step count retrieval must use CloudID method (base library 2.7.0+):
  • Frontend:
    wx.getWeRunData()
    to get cloudID, use
    wx.cloud.CloudID(cloudID)
    to pass to cloud function
  • Cloud Function: Directly use
    weRunData.data
    to get decrypted step count data, check
    weRunData.errCode
    to handle errors
  • Forbidden: Do not use session_key manual decryption method, CloudID is more secure and simple
  • Required: Must implement fallback mechanism (simulated data) to handle cloudID retrieval failure cases
微信步数获取必须使用CloudID方式(基础库2.7.0及以上)
  • 前端:调用
    wx.getWeRunData()
    获取cloudID,使用
    wx.cloud.CloudID(cloudID)
    传递至云函数
  • 云函数:直接使用
    weRunData.data
    获取解密后的步数数据,检查
    weRunData.errCode
    处理错误
  • 禁止:请勿使用session_key手动解密方式,CloudID更安全简便
  • 要求:必须实现降级机制(模拟数据)以处理cloudID获取失败的情况

Cloud Function Deployment and Permission Notes

云函数部署与权限说明

  • After AI automatically deploys cloud functions, special permissions like cloud invocation may be missing
  • Recommend users to right-click cloud function in WeChat Developer Tools, select "Install Dependencies in Cloud"
  • For functions requiring cloud invocation permissions (such as WeChat step count decryption), recommend manually deploying once via Developer Tools to get complete permissions
  • If encountering permission issues, prompt user to check cloud function's service authorization and API permission configuration
  • AI自动部署云函数后,可能会缺失云调用等特殊权限
  • 建议用户在WeChat Developer Tools中右键点击云函数,选择"云端安装依赖"
  • 对于需要云调用权限的函数(如微信步数解密),建议通过开发者工具手动部署一次以获取完整权限
  • 若遇到权限问题,提示用户检查云函数的服务授权与API权限配置

Development Workflow Guidance

开发流程指引

  • After completing mini program project development, proactively suggest user to use WeChat Developer Tools for preview, debugging, and publishing
  • If user agrees, use CLI command to open WeChat Developer Tools, pointing to project root directory containing
    project.config.json
  • Remind user to perform real device preview, debugging, and publishing operations in WeChat Developer Tools
  • 完成小程序项目开发后,主动建议用户使用WeChat Developer Tools进行预览、调试与发布
  • 若用户同意,使用CLI命令打开WeChat Developer Tools,指向包含
    project.config.json
    的项目根目录
  • 提醒用户在WeChat Developer Tools中进行真机预览、调试与发布操作