miniprogram-development

独立安装说明

如果此环境仅安装了当前技能，请从 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 或小程序部署/调试工作流。

同时还需阅读

• CloudBase 认证 -> ../auth-wechat/SKILL.md（独立备用：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（独立备用：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/no-sql-wx-mp-sdk/SKILL.md）
• 小程序微信支付或集成中心生成的支付功能 -> ../cloudbase-wechat-integration/SKILL.md（独立备用：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（独立备用：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 约束。
• 在未首先遵循变更安全协议（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. 按场景路由

   • 如果任务涉及 CloudBase、wx.cloud、云函数、CloudBase 数据库/存储或 CloudBase 身份处理，请阅读 CloudBase 集成参考
   • 如果任务涉及调试、预览、发布、微信开发者工具或无开发者工具工作流，请阅读 调试和预览参考
   • 如果任务涉及 tabBar、图标资源或标签间距，除非用户明确要求图标，否则优先使用下面仅文本的自定义 tabBar 默认值

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

   • CloudBase 是一个重要的小程序集成路径，但不是通用要求
   • 仅当项目使用 CloudBase 时，才应用 CloudBase 特定的认证、数据库、存储或云函数约束

5. 推荐正确的预览/调试路径

   • 优先使用微信开发者工具进行模拟器、面板调试、预览和真机验证
   • 如果微信开发者工具不可用，酌情使用 miniprogram-ci 进行预览、上传和 npm 构建工作流

---

微信小程序开发规则

通用项目规则

1. 项目结构

   • 小程序代码应遵循 project.config.json 中配置的项目根目录
   • 保持页面级文件完整，包括 .json 配置文件
   • 确保引用的本地资源实际存在，以避免编译失败

2. 配置检查

   • 在打开、预览或发布项目前检查 project.config.json
   • 当需要真实预览、上传或微信开发者工具工作流时，确认 appid 可用
   • 确认 miniprogramRoot 和相关路径设置正确

3. 资源处理

   • 对于 tabBar，当用户未明确需要图标时，默认优先使用仅文本的自定义 tabBar。这避免了图标资源处理，移除了预留的图标空间，使标签区域更易对齐。
   • 仅当用户明确要求标签图标或设计需要时，才生成本地图标资源并配置 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 来移除标签上方的空白区域。仅当用户明确想要基于图标的标签时，才切换到下载的本地图标。

CloudBase 作为小程序子场景

• 如果用户明确使用 CloudBase、wx.cloud、腾讯云开发或云开发，请遵循 CloudBase 集成参考
• 在 CloudBase 小程序项目中，适当使用 wx.cloud API 和 CloudBase 环境配置
• 不要将 CloudBase 特定规则应用于非 CloudBase 小程序项目

调试、预览和发布

• 如果微信开发者工具可用，将其作为模拟器调试、面板检查、预览和设备验证的主要路径
• 如果微信开发者工具不可用，使用 miniprogram-ci 作为预览、上传和 npm 构建相关自动化的备用路径
• 有关详细工作流，请阅读 调试和预览参考

最小项目骨架

app.js

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

pages/index/index.js

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

pages/index/index.wxml

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

pages/index/index.json

{
  "navigationBarTitleText": "Home"
}

project.config.json

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

参考

• CloudBase 小程序集成 — 当小程序项目明确集成 CloudBase 时使用
• 微信开发者工具调试和预览 — 用于调试、预览、发布和无开发者工具备用工作流
• 常见陷阱 — 在生成可选链、TDesign 样式、Canvas + 存储和环境问题的代码前阅读