独立安装说明

若当前环境仅安装了本技能，请从 CloudBase 主入口启动，并对同级技能使用已发布的 cloudbase/references/... 路径。

• CloudBase 主入口：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• 当前技能原始源文件：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/miniprogram-development/SKILL.md

对于随当前技能目录一同分发的文件，保留本地 references/... 路径。当本文件引用了 auth-tool 或 web-development 等同级技能时，请使用紧邻该引用处所标注的独立备用 URL。

跨领域协议（代码修改或上传前必须遵守）：

• 变更安全协议：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署关卡：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/deployment-gate.md

激活契约

首次使用本技能的适用场景

• 用户请求涉及微信小程序结构、页面、预览、发布，或 CloudBase 小程序集成相关内容。

编码前须阅读的条件

• 用户提到了 wx.cloud、CloudBase 小程序、OPENID、小程序部署/调试工作流、Nightly DevTools、wechatide 或微信 IDE Skills。

还需一并阅读

• CloudBase 认证 → ../auth-wechat/SKILL.md（独立备用 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-wechat/SKILL.md）
• CloudBase 文档数据库 → ../no-sql-wx-mp-sdk/SKILL.md（独立备用 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/no-sql-wx-mp-sdk/SKILL.md）
• 小程序微信支付或 Integration Center 生成的支付函数 → ../cloudbase-wechat-integration/SKILL.md（独立备用 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-wechat-integration/SKILL.md；官方文档：https://docs.cloudbase.net/integration/wechat-pay-miniprogram/index.md）
• UI 生成 → 首先阅读 ../ui-design/SKILL.md（独立备用 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ui-design/SKILL.md）

禁止使用场景

• Web 端认证流程或 Web SDK 特定的前端实现。
• 微信支付、支付回调、退款或公众号 OAuth 细节；此类场景请使用 cloudbase-wechat-integration。

常见错误 / 注意事项

• 为小程序生成 Web 风格的登录流程。
• 将 Web SDK 的假设混入 wx.cloud 项目中。
• 在未确认项目实际使用 CloudBase 前，即套用 CloudBase 约束。
• 误认为稳定版微信开发者工具已包含 Nightly Skills / wechatide（实际情况可能并非如此）。
• 在 Nightly wechatide 已可满足日常小程序云操作的前提下，强制要求使用 CloudBase MCP 腾讯云登录。
• 虚构 wechatide 工具名称或命令行参数，而非使用 --help 或查阅 Nightly tools.yaml。
• 未遵循变更安全协议（cloudbase-platform/references/protocols/change-safety-protocol.md）即进行代码或配置修改。
• 未完成 cloudbase-platform/references/protocols/deployment-gate.md 中所列检查项即执行小程序上传/发布操作。

何时使用本技能

当需要进行微信小程序开发时，请使用本技能，具体包括：

• 构建或修改小程序页面与组件
• 组织小程序项目结构与配置
• 调试、预览或发布小程序项目
• 处理微信开发者工具相关工作流
• 处理小程序运行时行为、资源文件或页面配置文件
• 在明确需要时，将 CloudBase 集成至小程序项目中

禁止用于以下场景：

• Web 前端开发（请使用 web-development）
• 纯后端服务开发（请根据情况选用 cloudrun-development 或 cloud-functions）
• 无小程序开发上下文的纯 UI 设计任务（请使用 ui-design）

如何使用本技能（面向编码智能体）

1. 以通用小程序工作流为起点

   • 默认将微信小程序开发视为目标范围
   • 除非用户明确说明或代码库中体现，否则不得假定项目使用 CloudBase

2. 遵循小程序项目规范

   • 将小程序源码置于配置的小程序根目录下
   • 确保页面文件包含必需的配置文件（如 index.json）
   • 在建议预览或 IDE 工作流前，先检查 project.config.json

3. 按场景路由

   • 若任务涉及调试、预览、发布、打开 DevTools、控制台/网络分析或 wechatide，请优先阅读调试与预览参考文档
   • 若需在微信 IDE Skills 与 CloudBase MCP 之间做出选择，请阅读《微信 IDE Skills vs CloudBase MCP》
   • 若任务涉及 CloudBase、wx.cloud、云函数、CloudBase 数据库/存储或 CloudBase 身份管理，请阅读 CloudBase 集成参考文档
   • 若任务涉及 tabBar、图标资源或标签间距，默认优先采用下方纯文本自定义 tabBar 方案，除非用户明确要求使用图标

4. 仅在适用时应用 CloudBase 规则

   • CloudBase / 微信云开发 是一条重要的小程序集成路径，但并非通用前提
   • 仅当项目确已使用 CloudBase 时，才应用其特有的认证、数据库、存储或云函数约束

5. 推荐恰当的预览/调试/云操作路径

   • 优先采用 Nightly 版微信开发者工具（内置 Skills/MCP），并在可用时通过 wechatide 执行 —— 参见 devtools-debug-preview.md
   • Nightly 下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly_backup.html
   • 若 Nightly / wechatide 不可用，则回退至 miniprogram-ci 进行预览/上传，并使用 CloudBase MCP 管理云资源

微信小程序开发规则

通用项目规则

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

{
  "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、Tencent CloudBase、腾讯云开发 或 云开发，请遵循 CloudBase 集成参考文档
• 在 CloudBase 小程序项目中，应恰当使用 wx.cloud API 及 CloudBase 环境配置
• 切勿将 CloudBase 特有规则应用于非 CloudBase 小程序项目

调试、预览与发布

• 优先采用 Nightly 版开发者工具 + wechatide：支持打开项目、编译、模拟器、控制台/网络调试、预览、上传及日常云操作（微信登录 — 无需单独腾讯云登录）
• 始终传入必要上下文： -c 、绝对路径 --project、有效 appid，以及按需提供的云 env
• 若 Nightly / wechatide 不可用，则以 miniprogram-ci 作为预览/上传/npm 的回退方案，并使用 CloudBase MCP 管理云资源；同时提示用户安装 Nightly 以获得完整 Skills/MCP 支持
• 详细工作流请参阅《调试与预览参考》及《微信 IDE Skills vs CloudBase MCP》

最小化项目骨架

app.js

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

pages/index/index.js

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

pages/index/index.wxml

  {{message}}

pages/index/index.json

{
  "navigationBarTitleText": "Home"
}

project.config.json

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

参考文档

• CloudBase 小程序集成 — 当小程序项目明确集成 CloudBase 时使用
• 微信开发者工具调试与预览 — Nightly / wechatide 路径、必需上下文及无 Nightly 时的回退方案
• 微信 IDE Skills vs CloudBase MCP — 分层逻辑及各执行面的适用时机
• 常见陷阱 — 在生成可选链、TDesign 样式、Canvas + 存储及环境相关代码前必读