微信小程序开发

技能文档

---
name: miniprogram-development
title: 微信小程序开发
category: 开发工具
description: 微信小程序开发技能，覆盖项目结构与配置（project.config.json、appid、miniprogramRoot、tabBar、路由与图标资产）、开发者工具 Nightly 工作流（wechatide CLI）、miniprogram-ci 预览上传、控制台/网络调试、消息推送与客服消息自动回复、小程序搜索优化（页面收录、mpcrawler），以及明确使用时的 CloudBase（wx.cloud、腾讯云开发）集成。当用户需要创建、开发、修改、调试、预览、发布或推广微信小程序，或提到小程序开发、云开发、消息推送、客服自动回复、小程序 SEO 时触发。
---

# 微信小程序开发

本技能面向微信小程序的构建、调试、预览、发布与优化，并在项目明确使用时覆盖 CloudBase（腾讯云开发）集成。

## 技能工作流

### 步骤1：确认任务范围

- 先按通用小程序开发流程处理，除非用户或代码库明确表明项目使用 CloudBase，否则不要假定其存在
- 明确排除场景：纯 Web 前端开发、纯后端服务开发、与小程序开发无关的纯 UI 设计任务
- 若用户提到 `wx.cloud`、CloudBase、腾讯云开发、云开发、OPENID 或小程序部署调试工作流，进入 CloudBase 子场景（见步骤4）

### 步骤2：检查项目结构与配置

- 小程序代码应位于 `project.config.json` 中配置的项目根目录（`miniprogramRoot`）内
- 保持页面级文件完整，包括必需的 `.json` 配置文件（如 `index.json`）
- 在打开、预览或发布项目前，先检查 `project.config.json`：确认 `appid` 可用、`miniprogramRoot` 等路径配置正确
- 确保引用的本地资源（如图标）真实存在，避免编译失败；生成资产引用时把文件下载进项目

### 步骤3：按场景路由到参考文档

- 任务涉及调试、预览、发布、打开开发者工具、控制台/网络调试或 `wechatide` → 先读 [调试与预览参考](references/devtools-debug-preview.md)
- 需要在微信 IDE Skills 与 CloudBase MCP 之间做选择 → 读 [微信 IDE Skills 与 CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)
- 任务涉及 CloudBase、`wx.cloud`、云函数、云数据库/云存储或身份处理 → 读 [CloudBase 集成参考](references/cloudbase-integration.md)
- 任务涉及小程序搜索优化、页面收录、搜索推广、关键词排名 → 先读 [小程序 SEO 与微信搜索优化](references/seo-search-optimization.md)
- 任务涉及消息推送、客服消息自动回复、MsgType/Event → 云函数绑定或推送相关函数日志 → 读 [消息推送与客服自动回复](references/message-push-customer-service.md)
- 任务涉及 `tabBar`、图标资产或标签间距 → 默认采用下文的纯文本自定义 `tabBar` 方案，除非用户明确要求图标
- 生成代码前先读 [常见陷阱](references/pitfalls.md)（可选链、TDesign 样式、Canvas + 缓存、环境问题）

### 步骤4：仅在适用时应用 CloudBase 规则

- CloudBase / 微信云开发是重要的小程序集成路径，但不是通用要求；仅当项目确实使用 CloudBase 时才应用其鉴权、数据库、存储与云函数约束
- CloudBase 小程序项目中合理使用 `wx.cloud` API 与环境配置
- 不要把 CloudBase 专属规则套用到非 CloudBase 小程序项目上

### 步骤5：选择正确的预览/调试/云操作路径

- 优先使用微信开发者工具 **Nightly** 版（内置 Skills/MCP），通过 `wechatide` 执行（微信登录，无需单独登录腾讯云），详见 [调试与预览参考](references/devtools-debug-preview.md)
- Nightly 下载：https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html
- Nightly / `wechatide` 不可用时，回退到 `miniprogram-ci` 做预览/上传，云资源操作走 CloudBase MCP；并提示用户安装 Nightly 以获得完整 Skills/MCP 能力
- 始终传入必要上下文：`-c <clientName>`、绝对路径 `--project`、有效 `appid`，需要时附带云环境 `env`
- 不要凭空编造 `wechatide` 的工具名或参数，使用 `--help` 或 Nightly 的 `tools.yaml` 确认

## 开发规则

### 通用项目规则

1. **项目结构**
   - 小程序代码遵循 `project.config.json` 配置的项目根
   - 页面级文件保持完整，包括 `.json` 配置
   - 引用的本地资源必须真实存在，避免编译失败

2. **配置检查**
   - 打开、预览、发布前检查 `project.config.json`
   - 真机预览、上传或开发者工具工作流需要确认 `appid` 可用
   - 确认 `miniprogramRoot` 与相关路径设置正确

3. **资源处理**
   - `tabBar`：用户未明确需要图标时，默认使用纯文本自定义 `tabBar`，避免图标资产处理、去掉预留图标空间、让标签区域更易对齐
   - 仅当用户明确要求 tab 图标或设计需要时，才生成本地图标资产并配置 `iconPath` / `selectedIconPath`
   - 保持文件路径稳定并与小程序配置文件一致

### 简单 `tabBar` 的推荐默认方案

设置 `tabBar.custom = true`，`app.json` 中只保留 `pagePath` 和 `text`，自定义组件内渲染纯文本项，从而没有图标槽位、标签上方没有多余空白。

`app.json`

```json
{
  "tabBar": {
    "custom": true,
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/travel/travel", "text": "行程" },
      { "pagePath": "pages/my/my", "text": "我的" }
    ]
  }
}
```

自定义 `tabBar` 保持纯文本布局，用 flex 居中或匹配 `height` 与 `line-height` 消除标签上方空白。仅当用户明确想要图标式 tab 时才切换到下载的本地图标。

### CloudBase 作为小程序子场景

- 用户明确使用 CloudBase、`wx.cloud`、腾讯云开发或云开发时，遵循 [CloudBase 集成参考](references/cloudbase-integration.md)
- CloudBase 小程序项目中合理使用 `wx.cloud` API 与环境配置
- 不对非 CloudBase 项目套用 CloudBase 规则

### 调试、预览与发布

- 优先 Nightly 开发者工具 + `wechatide`：打开项目、编译、模拟器、控制台/网络调试、预览、上传及日常云操作（微信登录，无需单独腾讯云登录）
- 始终传入必要上下文：`-c <clientName>`、绝对路径 `--project`、有效 `appid`，需要时附带云环境 `env`
- Nightly / `wechatide` 不可用时，用 `miniprogram-ci` 回退处理预览/上传/npm，云资源走 CloudBase MCP；提示用户安装 Nightly 获得完整 Skills/MCP
- 详细工作流读 [调试与预览参考](references/devtools-debug-preview.md) 与 [微信 IDE Skills 与 CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)

### 消息推送与客服自动回复

> 微信生态专章：消息推送 / 客服自动回复细节以中文参考文档为准（术语保留英文 API 名）。

- 当前唯一运维路径：微信开发者工具 IDE + wxide CLI。在 `cloud_query_msg_push` / `cloud_manage_msg_push` 尚未暴露期间，不要讲授底层旁路方案
- 用 `cloud_fn_deploy` **并加** `--remote-npm-install` 部署接收函数；在 IDE 消息推送面板绑定 (MsgType, Event) → 云函数，直至 CLI 工具支持
- 客服自动回复必须使用 `cloud.openapi.customerServiceMessage.send` 并在 `config.json` 配置 openapi 权限——仅靠云函数返回值不会回复
- 函数日志：IDE **云开发控制台 → 云函数 → 日志**；wxide CLI 暂不支持日志查询——不要讲授底层日志 CGI 旁路
- 完整参考：[消息推送与客服自动回复](references/message-push-customer-service.md)

## 最小项目骨架

`app.js`

```js
App({
  onLaunch() {
    console.log("Mini Program launched");
  },
});
```

`pages/index/index.js`

```js
Page({
  data: {
    message: "Hello CloudBase Mini Program",
  },
});
```

`pages/index/index.wxml`

```xml
<view class="page">
  <text>{{message}}</text>
</view>
```

`pages/index/index.json`

```json
{
  "navigationBarTitleText": "Home"
}
```

`project.config.json`

```json
{
  "appid": "your-mini-program-appid",
  "projectname": "cloudbase-mini-program",
  "miniprogramRoot": "./",
  "compileType": "miniprogram"
}
```

## 常见错误

- 为小程序生成 Web 风格的登录流程
- 把 Web SDK 的假设混入 `wx.cloud` 项目
- 未确认项目确实使用 CloudBase 就套用其约束
- 以为稳定版开发者工具包含 Nightly Skills/`wechatide`（可能没有）
- Nightly `wechatide` 已能覆盖日常云操作时，仍强行要求 CloudBase MCP 腾讯云登录
- 凭空编造 `wechatide` 工具名或参数，而不使用 `--help` / Nightly `tools.yaml`
- 在 `cloud_*_msg_push` 暴露前绕过 wxide CLI / IDE 用底层传输做消息推送操作（见 [消息推送与客服自动回复](references/message-push-customer-service.md)）
- 以为云函数返回值会自动回复客服会话（必须用 `cloud.openapi.customerServiceMessage.send`）

## 参考资料

- [CloudBase 小程序集成](references/cloudbase-integration.md) — 项目明确集成 CloudBase 时使用
- [微信开发者工具调试与预览](references/devtools-debug-preview.md) — Nightly / `wechatide` 路径、必要上下文与无 Nightly 回退
- [微信 IDE Skills 与 CloudBase MCP](references/wxide-vs-cloudbase-mcp.md) — 分层与执行面选择
- [消息推送与客服自动回复](references/message-push-customer-service.md) — 经 wxide CLI + IDE 的消息推送 / 客服自动回复
- [小程序 SEO 与微信搜索优化](references/seo-search-optimization.md) — 页面收录、搜索推广（`mpcrawler`、URL 可达性、`navigator` 跳转、标题与缩略图）
- [常见陷阱](references/pitfalls.md) — 生成代码前阅读：可选链、TDesign 样式、Canvas + 缓存、环境问题

使用说明

# 微信小程序开发

微信小程序开发技能，覆盖项目搭建、调试、预览、发布、搜索优化，以及消息推送与客服自动回复，明确使用时支持 CloudBase（腾讯云开发）集成。

## 使用

对 Agent 说：

```text
帮我创建一个微信小程序项目并预览
```

```text
用开发者工具把这个小程序上传为体验版
```

```text
给小程序加客服消息自动回复 / 做小程序搜索优化
```

## 工作原理

技能按任务场景路由到对应参考文档：项目结构与配置检查 → 调试预览（优先微信开发者工具 Nightly 的 `wechatide` CLI，回退 `miniprogram-ci`）→ CloudBase 集成（`wx.cloud`）→ 消息推送与客服消息 → 小程序 SEO。开发前请阅读常见陷阱清单，避免可选链语法、TDesign 样式覆盖等高频错误。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。