miniprogram-development · v2.33.0 · 2026-09-04 · sha256 90b3a91302b22338
miniprogram-development v2.33.0A
Immutable. This exact content is served forever at /api/v1/blob/90b3a91302b22338.
---
name: miniprogram-development
description: WeChat Mini Program development skill for building, debugging, previewing, testing, publishing, and optimizing mini program projects (小程序开发、调试、预览、发布). Covers project structure and config (`project.config.json`, `appid`, `miniprogramRoot`, `tabBar`, routing/navigation, icon assets), WeChat Developer Tools Nightly workflows (`wechatide` CLI, WeChat IDE Skills/MCP), `miniprogram-ci` preview/upload, console/network debugging, message push (消息推送) and customer-service auto-reply (客服消息), mini program SEO / search indexing (小程序搜索优化、页面收录、搜索推广、mpcrawler), and CloudBase integration (`wx.cloud`, 腾讯云开发, 云开发) when explicitly used. Use when users create, develop, modify, debug, preview, deploy, publish, or promote WeChat Mini Programs. NOT for Web frontend (use web-development), pure backend services (use cloudrun-development / cloud-functions), or UI-design-only tasks (use ui-design).
version: 2.33.0
alwaysApply: false
---
## Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context.
**Cross-cutting protocols** (required before code changes or deployments):
- Change Safety Protocol: `../cloudbase-platform/references/protocols/change-safety-protocol.md`
- Deployment Gate: `../cloudbase-platform/references/protocols/deployment-gate.md`
## Activation Contract
### Use this first when
- The request is about WeChat Mini Program structure, pages, preview, publishing, or CloudBase mini program integration.
### Read before writing code if
- The user mentions `wx.cloud`, CloudBase mini programs, OPENID, mini program deployment/debug workflows, Nightly DevTools, `wechatide`, or WeChat IDE Skills.
- The user mentions message push (消息推送), customer-service auto-reply (客服消息/自动回复), or binding MsgType/Event callbacks to cloud functions.
### Then also read
- CloudBase auth -> `../auth-wechat-miniprogram/SKILL.md`
- CloudBase document DB -> `../cloudbase-document-database-in-wechat-miniprogram/SKILL.md`
- Mini Program WeChat Pay, 虚拟支付 (virtual payment, `wx.requestVirtualPayment`), or Integration Center generated payment functions -> `../cloudbase-wechat-integration/SKILL.md` (official docs: `https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md`)
- UI generation -> `../ui-design/SKILL.md` first
### Do NOT use for
- Web auth flows or Web SDK-specific frontend implementation.
- WeChat Pay, 虚拟支付 / `wx.requestVirtualPayment`, payment callbacks, refunds, or Official Account OAuth details; use `cloudbase-wechat-integration` for those scenarios.
### Common mistakes / gotchas
- Generating a Web-style login flow for mini programs.
- Mixing Web SDK assumptions into `wx.cloud` projects.
- Applying CloudBase constraints before confirming the project actually uses CloudBase.
- Assuming Stable WeChat Developer Tools includes Nightly Skills/`wechatide` (it may not).
- Forcing CloudBase MCP Tencent Cloud login for daily mini program cloud ops when Nightly `wechatide` already works.
- Inventing `wechatide` tool names or flags instead of using `--help` / Nightly `tools.yaml`.
- Bypassing wxide CLI / IDE for message-push ops with low-level transport before `cloud_*_msg_push` is exposed (see [message-push-customer-service.md](references/message-push-customer-service.md)).
- Assuming cloud-function return values auto-reply to customer-service chats (must use `cloud.openapi.customerServiceMessage.send`).
- Making code or configuration changes without first following the Change Safety Protocol (`cloudbase-platform/references/protocols/change-safety-protocol.md`).
- Performing mini program upload/publish without first completing the checks in `cloudbase-platform/references/protocols/deployment-gate.md`.
## When to use this skill
Use this skill for **WeChat Mini Program development** when you need to:
- Build or modify mini program pages and components
- Organize mini program project structure and configuration
- Debug, preview, or publish mini program projects
- Work with WeChat Developer Tools workflows
- Handle mini program runtime behavior, assets, or page config files
- Integrate CloudBase in a mini program project when explicitly needed
**Do NOT use for:**
- Web frontend development (use `web-development`)
- Pure backend service development (use `cloudrun-development` or `cloud-functions` as appropriate)
- UI design-only tasks without mini program development context (use `ui-design`)
---
## How to use this skill (for a coding agent)
1. **Start with the general mini program workflow**
- Treat WeChat Mini Program development as the default scope
- Do not assume the project uses CloudBase unless the user or codebase indicates it
2. **Follow mini program project conventions**
- Keep mini program source under the configured mini program root
- Ensure page files include the required configuration file such as `index.json`
- Check `project.config.json` before suggesting preview or IDE workflows
3. **Route by scenario**
- If the task involves debugging, previewing, publishing, opening DevTools, console/network, or `wechatide`, read [debug and preview reference](references/devtools-debug-preview.md) first
- If choosing between WeChat IDE Skills and CloudBase MCP, read [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)
- If the task involves CloudBase, `wx.cloud`, cloud functions, CloudBase database/storage, or CloudBase identity handling, read [CloudBase integration reference](references/cloudbase-integration.md)
- If the task involves mini program SEO / WeChat search optimization / page indexing / search promotion (小程序搜索优化、页面收录、搜索推广、关键词排名), read [Mini Program SEO & WeChat Search Optimization](references/seo-search-optimization.md) first
- If the task involves message push (消息推送), customer-service auto-reply (客服消息自动回复), MsgType/Event → cloud function binding, or push-related function logs, read [Message Push & Customer Service Auto-Reply](references/message-push-customer-service.md) first
- If the task involves `tabBar`, icon assets, or label spacing, prefer the text-only custom `tabBar` default below unless the user explicitly requires icons
4. **Use CloudBase rules only when applicable**
- CloudBase / 微信云开发 is an important mini program integration path, but not a universal requirement
- Only apply CloudBase-specific auth, database, storage, or cloud function constraints when the project is using CloudBase
5. **Recommend the right preview/debug/cloud-ops path**
- Prefer **Nightly** WeChat Developer Tools (built-in Skills/MCP) and execute via `wechatide` when available — see [devtools-debug-preview.md](references/devtools-debug-preview.md)
- Nightly download: https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html
- If Nightly / `wechatide` is unavailable, fall back to `miniprogram-ci` for preview/upload and CloudBase MCP for cloud resources
---
# WeChat Mini Program Development Rules
## General Project Rules
1. **Project Structure**
- Mini program code should follow the project root configured in `project.config.json`
- Keep page-level files complete, including `.json` configuration files
- Ensure referenced local assets actually exist to avoid compile failures
2. **Configuration Checks**
- Check `project.config.json` before opening, previewing, or publishing a project
- Confirm `appid` is available when a real preview, upload, or WeChat Developer Tools workflow is required
- Confirm `miniprogramRoot` and related path settings are correct
3. **Resource Handling**
- For `tabBar`, prefer a text-only custom `tabBar` by default when the user does not explicitly need icons. This avoids icon asset handling, removes reserved icon space, and makes the label area easier to align.
- Only generate local icon assets and configure `iconPath` / `selectedIconPath` when the user explicitly asks for tab icons or the design requires them.
- When generating local asset references such as icons, ensure the files are downloaded into the project.
- Keep file paths stable and consistent with mini program config files.
### Recommended default for simple `tabBar`
Use `tabBar.custom = true`, keep only `pagePath` and `text` in `app.json`, and render text-only items in the custom component so there is no icon slot and no extra blank area above the label.
`app.json`
```json
{
"tabBar": {
"custom": true,
"list": [
{ "pagePath": "pages/index/index", "text": "首页" },
{ "pagePath": "pages/travel/travel", "text": "行程" },
{ "pagePath": "pages/my/my", "text": "我的" }
]
}
}
```
Keep the custom `tabBar` layout text-only, and use flex centering or matching `height` and `line-height` to remove the blank area above the label. Switch to downloaded local icons only when the user explicitly wants icon-based tabs.
## CloudBase as a Mini Program Sub-Scenario
- If the user explicitly uses CloudBase, `wx.cloud`, Tencent CloudBase, 腾讯云开发, or 云开发, follow the CloudBase integration reference
- In CloudBase mini program projects, use `wx.cloud` APIs and CloudBase environment configuration appropriately
- Do not apply CloudBase-specific rules to non-CloudBase mini program projects
## Debugging, Preview, and Publishing
- Prefer **Nightly** DevTools + `wechatide` for open project, compile, simulator, console/network debug, preview, upload, and daily cloud ops (WeChat login — no separate Tencent Cloud login)
- Always pass required context: `-c <clientName>`, absolute `--project`, valid `appid`, and cloud `env` when needed
- If Nightly / `wechatide` is not available, use `miniprogram-ci` as the fallback for preview/upload/npm, and CloudBase MCP for cloud resources; tell the user to install Nightly for full Skills/MCP
- For detailed workflows, read [debug and preview reference](references/devtools-debug-preview.md) and [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md)
## Message Push & Customer Service Auto-Reply
> 微信生态专章：消息推送 / 客服自动回复细节以中文 reference 为准（术语保留英文 API 名）。
- **Current only ops path:** WeChat Developer Tools IDE + wxide CLI. Do not teach low-level bypasses while `cloud_query_msg_push` / `cloud_manage_msg_push` are not yet exposed (pending WeChat IDE CLI support).
- Deploy receiver functions with `cloud_fn_deploy` **and** `--remote-npm-install`; bind (MsgType, Event) → one cloud function in the IDE message-push panel until CLI tools land.
- Customer-service auto-reply requires `cloud.openapi.customerServiceMessage.send` plus `config.json` openapi permissions — function return values alone do not reply.
- Function logs: IDE **云开发控制台 → 云函数 → 日志**; the wxide CLI does not expose log query yet — do not teach low-level log CGI bypasses.
- Full reference: [Message Push & Customer Service Auto-Reply](references/message-push-customer-service.md)
## Minimal project skeleton
`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"
}
```
## References
- [CloudBase Mini Program Integration](references/cloudbase-integration.md) — use this when the mini program project explicitly integrates CloudBase
- [WeChat DevTools Debug and Preview](references/devtools-debug-preview.md) — Nightly / `wechatide` paths, required context, and no-Nightly fallbacks
- [WeChat IDE Skills vs CloudBase MCP](references/wxide-vs-cloudbase-mcp.md) — layering and when to use which execution surface
- [Message Push & Customer Service Auto-Reply](references/message-push-customer-service.md) — 消息推送 / 客服自动回复 via wxide CLI + IDE (no low-level bypass; pending `cloud_*_msg_push`)
- [Mini Program SEO & WeChat Search Optimization](references/seo-search-optimization.md) — 小程序搜索优化 / page indexing / search promotion (`mpcrawler`, URL reachability, `navigator` jumps, titles & thumbnails)
- [Common Pitfalls](references/pitfalls.md) — read before generating code for optional chaining, TDesign styling, Canvas + storage, and environment issues