CloudBase 全栈小程序开发

一个小程序要真正跑起来，缺的从来不是页面，是后端那一半：数据存哪、登录怎么做、图片传到哪、消息怎么发、审核怎么过。这个技能按「从想法到上架」的顺序组织，每一步告诉你调哪个工具、去哪取细节。

配方正文不打包，用 CloudBase MCP 的知识库按需检索（见文末）。这样内容永远跟线上最新版一致。

第 0 步：先问清三件事，别急着写代码

要确认	为什么
小程序 appid 与主体类型	个人 / 个体工商户 / 企业主体决定能用哪些能力（支付、部分类目）。测试号不支持云开发
后端是否用 云开发（CloudBase）	不用云开发就走另一条路，本技能不适用
云开发环境是国内站还是国际站	两套账号体系互不相通，选错的表现是「登录了但环境列表空」

还有一个高频坑：DevTools 里「云开发」入口是灰的，或者看不到环境——先诊断，不要当成工具 bug。常见原因就是上表第三条（主体不支持 / 绑定账号不一致 / 站点错）。诊断路径：searchKnowledgeBase({ mode: "skill", skillName: "miniprogram-development" }) 的 Common Pitfalls 一节。

第 1 步：接上 CloudBase MCP

技能包不能携带 MCP 配置，这一步必须显式做。三条路径按客户端能力选：

# A. 能跑命令的客户端
claude mcp add --transport http cloudbase https://tcb-api.cloud.tencent.com/mcp/v1

# B. 本地 stdio（需要 API Key，或要用远程缺的工具）
claude mcp add cloudbase -- npx -y @cloudbase/cloudbase-mcp@latest

# C. 客户端不支持 MCP 但有终端（走 mcporter 桥）
npx -y mcporter@0.16.1 call --stdio "npx -y @cloudbase/cloudbase-mcp@latest" auth action=status

图形客户端（Cursor、Qoder）只能让用户手动加：类型 HTTP / Streamable HTTP，地址填 /mcp/v1。

验证：调 auth action=status，返回 auth_status: READY 且带 current_env_id 就通了。

第 2 步：先跑通一个最小闭环，再谈功能

顺序固定，不要跳：

1. 建环境并绑定：manageEnv（查/建）→ auth(action="set_env", envId=...) 绑定。
2. 建一个集合：writeNoSqlDatabaseStructure。
3. 写一条数据：writeNoSqlDatabaseContent。
4. 写一个云函数并部署：manageFunctions，创建后在 DevTools 里「上传并部署：云端安装依赖」；用 MCP 的 queryFunctions / queryLogs 验证调用与日志。
5. 小程序端读这条数据：wx.cloud.init({ env }) → wx.cloud.database().collection(...).get()。

这五步通了，说明环境、权限、网络都对了；后面加页面只是重复。

第 3 步：按任务路由

要做的事	首选工具 / 技能
项目脚手架、project.config.json、miniprogramRoot、tabBar	searchKnowledgeBase → miniprogram-development
数据库集合、索引、权限规则	writeNoSqlDatabaseStructure / manageDataModel
增删改查（小程序端 / 云函数端）	writeNoSqlDatabaseContent / readNoSqlDatabaseContent + skill cloudbase-document-database-in-wechat-miniprogram
云函数（含 scf_bootstrap、定时触发）	manageFunctions + skill cloud-functions
图片/文件上传	manageStorage + skill cloud-storage-web
登录、openid、用户体系	skill auth-wechat-miniprogram（先在控制台配登录方式）
订阅消息 / 客服消息	skill miniprogram-development 的消息推送一节
预览、上传代码、提交审核	miniprogram-ci，或 DevTools Nightly 的 wechatide CLI
页面长得不好看	skill ui-design
上线后出问题	queryLogs / skill ops-inspector

第 4 步：发布链

体验版 → 上传代码 → 提交审核 → 发布。三步都有各自的坑：

• 预览/上传优先用 miniprogram-ci（走密钥，可自动化）；想用 wechatide CLI 需要 Nightly 版 DevTools，没装就如实说「这是缺工具，不是环境限制」，等用户决定。
• 合法域名：小程序端只能请求已备案并配置的域名；走 wx.cloud 不受这个限制——这也是云开发省事的地方。
• 审核驳回最常见三类：类目与实际功能不符、有诱导分享、收集了不该收集的用户信息。这些只能提前避，工具帮不上。

细节从哪来

不要凭记忆写配置项和小程序 API 参数，先查再写：

想要什么	怎么取
某个技能的完整配方	searchKnowledgeBase({ mode: "skill", skillName: "<技能名>" })
官方文档段落	searchKnowledgeBase({ mode: "docs", action: "searchDocs", input: "订阅消息" })，再 action: "readDoc" + docPath 取全文
某个云 API 的参数	searchKnowledgeBase({ mode: "openapi", apiName: "<api>" })

可查的相关技能：miniprogram-development、cloudbase-document-database-in-wechat-miniprogram、auth-wechat-miniprogram、cloud-functions、cloud-storage-web、ui-design、ops-inspector、cloudbase-wechat-integration、spec-workflow。

四条红线

1. 先确认主体与站点，再动环境。测试号 / 个人主体不支持的能力，硬做只会白费。
2. 不要把密钥、AppSecret 写进小程序端代码——小程序包是可以被反编译的。
3. 改数据库权限规则、删集合、删云函数前说清后果。
4. 审核相关的事（类目、诱导分享、用户信息）先讲规则再动手，别等驳回才改。

常见失败对照

现象	多半是
DevTools 里云开发入口是灰的	测试号 / 主体不支持，或绑定账号不一致
登录成功但环境列表空	站点选错（国内 / 国际）
wx.cloud 调用报环境不存在	没 wx.cloud.init，或 envId 写错
云函数本地跑通、线上 500	依赖没装（「云端安装依赖」），或 scf_bootstrap 缺
图片上传成功但打不开	存储权限规则没放行读