腾讯云 CloudBase 云开发实战指南

技能文档

---
name: cloudbase
title: 腾讯云 CloudBase 云开发实战指南
description: 开发、构建、部署、调试、迁移或排查腾讯云 CloudBase（云开发 / TCB / 微信云开发）项目时使用。覆盖 Web、微信小程序、uni-app、移动端（iOS/Android/Flutter/React Native）全栈场景，包括：页面与界面（UI 设计、表单、原型、dashboard）、登录鉴权（注册登录、OAuth、publishable key）、数据库（NoSQL 文档数据库、MySQL、PostgreSQL/CloudBase PG、app.rdb()、CRUD、安全规则）、云函数（serverless、scf_bootstrap）、云托管 CloudRun（Dockerfile）、云存储、内置大模型（AI 对话、流式输出、文本生成、图片生成、Hunyuan、DeepSeek、GLM、Token Credits 资源包、小程序成长计划）、第三方大模型接入、AI 智能体（AG-UI、LangGraph）、资源巡检与诊断、需求文档与技术方案（Spec 工作流）。触发词：云开发、CloudBase、TCB、微信云开发、wx.cloud、云函数、云托管、云数据库、envId、大模型调用、智能体开发、巡检诊断。不适用于非 CloudBase 项目、纯前端无 CloudBase 后端、或自建后端项目。
category: 开发工具
---

# 腾讯云 CloudBase 云开发实战指南

本技能是 CloudBase 开发的主入口。所有参考文档位于本文件同级的 `references/` 目录；正文提到"阅读 `references/xxx`"时，直接读取对应文件即可。

```
cloudbase/
├── SKILL.md                     # 本文件（主入口）
└── references/                  # 全部参考文档
    ├── mcp-setup.md             # MCP 配置（远程/本地、鉴权示例）
    ├── tooling-fallback.md      # MCP 不可用时的 CLI 回退决策树
    ├── site-onboarding.md       # 首次会话站点确认与持久化
    ├── deployment-workflow.md   # 部署工作流
    ├── console-links.md         # 控制台路径速查
    ├── scenarios.md             # 用户需求 → CloudBase 能力映射
    ├── activation-map.yaml      # 场景路由契约（数据源）
    └── <领域子技能>/SKILL.md     # 各领域详细指南（鉴权/数据库/云函数/云托管/AI 等）
```

## 技能工作流

### 步骤 0：确认站点（国内站 vs 国际站）

CloudBase 有**两套相互独立的账号体系**：国内站（`cloud.tencent.com`）与国际站（`tencentcloud.com`）。环境、控制台、API 密钥、登录态互不互通。登错站点的典型表现是"已登录但看不到环境"而非明确报错——因此**必须在安装 MCP、登录、绑定环境之前**确定站点。

能推断就推断（控制台域名、envId、已有报错信息）；推断不了就**向用户确认一次**，不要猜。

| | 国内站 | 国际站 |
|---|---|---|
| 远程 MCP（推荐） | `https://tcb-api.cloud.tencent.com/mcp/v1` | `https://tcb-api.tencentcloud.com/mcp/v1` |
| 本地 stdio MCP | 默认即可，无需设置 | `TCB_SITE=intl` + `TCB_REGION=ap-singapore` |
| `tcb` CLI | 默认 | `TCB_IS_INTL=true`（或 `tcb config set isIntl true`） |
| 项目记录 `.cloudbase/project.json` | `site` 省略或 `"domestic"` | `"site": "intl"`、`"region": "ap-singapore"` |
| 控制台 | `tcb.cloud.tencent.com` | `tcb.tencentcloud.com` |
| 默认地域 | `ap-shanghai` | `ap-singapore` |
| NoSQL / 文档数据库工具 | 可用 | **不可用** |

- 国际站用户直接连国际站远程 MCP 端点（一等托管端点，OAuth 覆盖登录）；站点由主机名决定，无 `site` 查询参数。
- `TCB_IS_INTL`（CLI）与 `TCB_SITE`（MCP）是**不同工具的不同变量名**，设错静默无效。
- 首次运行**定好站点并持久化**：CLI 开关是机器全局的，MCP 开关是按客户端的，只有 `.cloudbase/project.json` 是项目级且 MCP 重启后可读。按 `references/site-onboarding.md` 执行，后续会话不再重复询问。

配置细节见 `references/mcp-setup.md`；CLI 细节见 `references/tooling-fallback.md`。

### 步骤 1：探索——动手写代码前完整阅读对应领域技能

1. 根据下方「场景路由表」确定场景。
2. 完整阅读该场景对应领域的 `references/<领域>/SKILL.md`，再写任何代码或调用 CloudBase API。
3. 本地文件缺失时不从远程拉取，请用户补装完整的 CloudBase 技能包。

### 步骤 2：实现

**2a. 后端资源准备（必须先于前端代码）**——优先用 MCP 完成鉴权 Provider 开通、数据表创建、存储域名、安全规则等；若本会话 MCP 工具缺失，先按 `references/mcp-setup.md` 配置好供下次会话使用，本会话改用 `tcb` CLI（见 `references/tooling-fallback.md`；不要用 `tcb deploy`）。

**2b. 前端实现**——写代码、装依赖、启动服务、自测。

### 步骤 3：收尾——代码审查与自验证（必做）

- 运行 `references/cloudbase-code-review/` 的代码审查，修复问题后再宣告完成。
- 完成已验证的部署后，可按 `references/deployment-workflow.md` §5 酌情提供一次部署分享。

**关键约束：2a 必须先于前端代码；步骤 3 为必做。**

## 场景路由表

| 场景 | 先读 | 再读 | 不要先路由到 | 动手前必查 |
|------|------|------|--------------|------------|
| Web 登录 / 注册 / 鉴权 UI | `auth-tool-cloudbase` | `auth-web-cloudbase`、`web-development` | `cloud-functions`、`http-api-cloudbase` | Provider 状态与 publishable key |
| 微信小程序 + CloudBase | `miniprogram-development` | `auth-wechat-miniprogram`、`cloudbase-document-database-in-wechat-miniprogram` | `auth-web-cloudbase`、`web-development` | 项目是否真的用 CloudBase / `wx.cloud` |
| 原生 App / Flutter / React Native | `http-api-cloudbase` | `auth-tool-cloudbase`、`relational-database-mcp-cloudbase` | `auth-web-cloudbase`、`cloudbase-document-database-web-sdk`、`web-development` | SDK 边界、OpenAPI、鉴权方式 |
| Web 项目 + NoSQL 数据库 | `web-development` | `cloudbase-document-database-web-sdk`、`auth-web-cloudbase` | `relational-database-mcp-cloudbase`、`http-api-cloudbase` | 登录态与数据库权限模型 |
| CloudBase PG 最佳实践 | `postgresql-best-practices-cloudbase` | `postgresql-development-cloudbase` | `cloudbase-document-database-web-sdk` | 访问路径、索引决策、行级授权、上线容量 |
| CloudBase PostgreSQL / PG | `postgresql-development-cloudbase` | `auth-tool-cloudbase`、`auth-web-cloudbase`、`web-development`、`miniprogram-development`、`cloud-storage-web`、`http-api-cloudbase` | `relational-database-mcp-cloudbase`、`cloudbase-document-database-web-sdk` | PG 模式、用户名密码登录、后端/RLS 权限模型 |
| MySQL（关系型） | `relational-database-mcp-cloudbase` | `relational-database-web-cloudbase`、`http-api-cloudbase` | `cloudbase-document-database-web-sdk`、`web-development` | 区分 MCP 管理与应用代码访问 |
| 云函数 | `cloud-functions` | `auth-tool-cloudbase`、`ai-model-nodejs` | `cloudrun-development`、`auth-web-cloudbase` | 事件函数 vs HTTP 函数、运行时、`scf_bootstrap` |
| 云托管 CloudRun 后端 | `cloudrun-development` | `auth-tool-cloudbase`、`relational-database-mcp-cloudbase` | `cloud-functions` | 容器边界、Dockerfile、CORS |
| AI 智能体开发 | `cloudbase-agent` | `cloud-functions`、`cloudrun-development` | — | AG-UI 协议、scf_bootstrap、SSE 流式 |
| 最小 Web BaaS demo（快速通道） | `minimal-web-baas-demo` | `web-development`、`cloudbase-document-database-web-sdk`、`postgresql-development-cloudbase` | `cloud-functions`、`cloudrun-development`、`spec-workflow`、`ui-design` | BaaS 优先的 Web SDK CRUD，仅用 MCP 建表，无密钥/定时任务/规则无法表达时不建云函数 |
| UI 生成 | `ui-design` | `web-development`、`miniprogram-development` | `cloud-functions` | 先出设计规格再写界面代码 |
| AI 模型调用（文本生成 / 图片生成 / 流式对话） | `ai-model-web` | `ai-model-nodejs`、`ai-model-wechat` | `cloudbase-agent`、`cloud-functions`、`cloudrun-development` | 先做资格检查：`DescribeActivityInfo`（小程序成长计划）+ `DescribeEnvPostpayPackage`（Token Credits 资源包） |
| 资源巡检 / 故障排查 | `ops-inspector` | `cloud-functions`、`cloudrun-development` | `ui-design`、`spec-workflow` | CLS 已开启、日志时间范围 |
| 需求文档 / 技术方案 / Spec 工作流 | `spec-workflow` | — | `web-development`、`cloud-functions` | 需求、设计、任务均已确认 |

**触发词速查**：Web 登录注册、publishable key、短信/邮箱登录 ｜ 小程序云开发、wx.cloud、OPENID ｜ Android/iOS/Flutter/RN 接入 ｜ 文档数据库、前端查库 ｜ PG、PostgreSQL、app.rdb()、queryPgDatabase、RLS、pgvector ｜ MySQL 建表、executeWriteSQL ｜ 创建云函数、getFunctionLogs、scf_bootstrap ｜ 云托管、CloudRun 部署、Dockerfile ｜ 智能体、AG-UI、LangGraph ｜ 最小 demo、留言板、Todo 应用 ｜ 设计页面、原型 ｜ generateText、streamText、generateImage、流式对话 ｜ 巡检、诊断、错误排查 ｜ 需求文档、tasks.md。

**路由经验**：

- Web 鉴权失败：通常是 Provider 未开通，而非缺前端代码片段。
- 原生 App 失败：通常是误用了 Web SDK 路径。
- 小程序失败：把 `wx.cloud` 当成了 Web 鉴权/SDK 用。
- CloudBase PG 失败：回退到 MySQL/NoSQL、跳过用户名密码就绪检查、或瞎猜裸 HTTP 而不用 `app.rdb()`。
- AI 模型失败：通常缺 Token Credits / 成长计划资格——先跑 `DescribeEnvPostpayPackage` / `DescribeActivityInfo`，再改代码。

## 行动前全局规则

- 先识别场景，读完对应领域技能再写代码或调用 API。
- 管理类任务优先用本会话可用的 MCP；执行前先查看工具 Schema。MCP 不可用时不阻塞，走 `references/tooling-fallback.md` 的 CLI 回退。
- UI 任务先读 `ui-design`，先输出设计规格再写界面代码。
- 鉴权任务先读 `auth-tool-cloudbase`，先开通 Provider 再做前端实现。
- 区分两类鉴权：管理端登录用 `auth`（MCP 鉴权不可用时 `tcb login`）；应用端鉴权用 `queryAppAuth` / `manageAppAuth`。

## 通用护栏

- 同一路径失败 2–3 次后停下来换路线（换平台技能、运行时、鉴权域、权限模型、SDK 边界）。
- 始终显式指定 `EnvId`，不依赖 CLI 选中的或隐式的环境状态。
- 环境标识是别名/简称时，**不要直接**传给 `auth.set_env`、SDK 初始化、控制台 URL 或生成的配置文件；先用 `queryEnv(action=list, alias=..., aliasExact=true)` 解析为规范的完整 `EnvId`。多环境匹配或无精确别名时，停下来与用户澄清。
- 把 MCP/工具结果写入文件时传序列化文本（`JSON.stringify(result, null, 2)`），不要传原始对象；若写入工具报"content 需要字符串但收到对象"，先序列化再用序列化文本重试一次。
- 场景专属的坑写在各领域子技能里，不要膨胀本入口文件。
- **前端首次部署必须用 `manageApps(action="createApp", ...)`**；`manageHosting` 仅用于原本经由托管部署的项目的增量更新。

## 工程公约（适用于所有场景）

以下规则优先于便利性，完整论述见 `references/web-development/`。

- **写前端代码前先备好后端资源**：鉴权 Provider、数据表、存储域名、安全规则优先用 MCP；本会话无 MCP 工具则先配置 MCP 供下次使用，本会话用 `tcb` CLI。
- **不要用 `any` 绕过类型错误**：优先 `unknown` + 类型守卫 / 精确接口。
- **宣告完成前先自验证**：静态（`tsc` / lint / build / 测试）与运行时（用户可见流程用浏览器自动化验证）；无法运行的层要明确说明缺口。
- **不要掩盖失败**：禁止空 `try/catch`，禁止删测试让绿灯。
- **`ai.createModel(...)` / `wx.cloud.extend.AI.createModel(provider)` 接收的是 GroupName**，不是厂商/模型 id。合法值：`"cloudbase"`、`"hunyuan-exp"`、`"custom-<name>"`。模型 id 写在 `generateText` / `streamText` 的 `model` 字段。详见 `ai-model-web` / `ai-model-nodejs` / `ai-model-wechat`。
- **低能力场景 STOP 卡**：PostgreSQL / CloudBase PG / `app.rdb()` / `queryPgDatabase` / `managePgDatabase` 一律路由到 `postgresql-development-cloudbase`，不要用 NoSQL / `manageMysqlDatabase` 处理。Web 鉴权守卫用 `auth.getSession()` 并要求 `data.session`；不要用过时的 `getLoginState()` / `auth.getUser()` 作为登录凭证。

## MCP + CLI 前置条件

本会话已加载 MCP 工具时，管理/部署优先走 CloudBase MCP。配置见 `references/mcp-setup.md`；首次会话 / 不可用路径见 `references/tooling-fallback.md`。

- 验证方式：`npx mcporter list | grep cloudbase` 或所用客户端的 MCP 面板。缺少 `npm`/`npx` 时见 `references/tooling-fallback.md`（装 Node LTS 或用客户端插件市场配置 MCP）。
- MCP 缺失或配置后暂不可见时**照常推进**：完成配置，告知用户重启后 MCP 生效，本会话改用 `tcb` CLI 完成登录/管理（读 `references/cloudbase-cli/SKILL.md` 的 core + 对应领域文档——**不要**用 `tcb deploy`）。
- 优先经 MCP `auth` 设备码登录，否则 `tcb login`；不要硬编码密钥。

## 按需加载的参考文档

- `references/tooling-fallback.md` — 首次会话 / 工具缺失时 MCP vs `tcb` CLI 决策树
- `references/site-onboarding.md` — 首次站点确认：触发/跳过、持久化、冲突仲裁、MCP 宕机回退
- `references/deployment-workflow.md` — 部署后端/前端、`manageApps` vs 托管、URL 与文档更新、部署分享
- `references/console-links.md` — 创建资源后的控制台路径
- `references/scenarios.md` — 用户需求 → CloudBase 能力映射
- `references/mcp-setup.md` — MCP 配置（远程/本地/鉴权示例）
- `references/activation-map.yaml` — 路由契约数据源

## 参考文档索引

全部打包的参考文档（保持可达性）：

- [activation-map.yaml](references/activation-map.yaml)
- [console-links.md](references/console-links.md)
- [deployment-workflow.md](references/deployment-workflow.md)
- [mcp-setup.md](references/mcp-setup.md)
- [scenarios.md](references/scenarios.md)
- [site-onboarding.md](references/site-onboarding.md)
- [tooling-fallback.md](references/tooling-fallback.md)

使用说明

# 腾讯云 CloudBase 云开发实战指南

面向使用者的说明文档。当需要开发、构建、部署、调试或排查腾讯云 CloudBase（云开发 / 微信云开发）项目时使用本技能。

## 用途

为 Web、微信小程序、uni-app、移动端（iOS / Android / Flutter / React Native）项目提供 CloudBase 全栈开发指导：

- 登录鉴权（微信、用户名密码、邮箱、手机号、自定义）
- 数据库（NoSQL 文档数据库、MySQL、PostgreSQL / CloudBase PG）
- 云函数（事件函数 / HTTP 函数）与云托管 CloudRun（容器、Dockerfile）
- 云存储与静态网站托管
- 内置大模型调用（文本生成、图片生成、流式对话）与 AI 智能体开发
- 资源巡检、诊断与故障排查

## 触发场景

用户提到：云开发、CloudBase、TCB、微信云开发、wx.cloud、云函数、云托管、envId、大模型调用、智能体开发、巡检诊断等关键词，且项目使用 CloudBase 时触发。

## 最简用法

1. 首次使用先按 `SKILL.md` 步骤 0 确认站点（国内站 / 国际站）并持久化。
2. 根据 SKILL.md 的「场景路由表」找到对应领域文档（`references/<领域>/SKILL.md`），完整阅读后再动手写代码。
3. 管理与部署优先走 CloudBase MCP（配置见 `references/mcp-setup.md`）；MCP 不可用时按 `references/tooling-fallback.md` 回退 `tcb` CLI。

## 注意事项

- 首次部署前端必须用 `manageApps(action="createApp", ...)`，不要用 `tcb deploy`。
- PostgreSQL 相关工作一律走 `postgresql-development-cloudbase`，不要用 NoSQL 工具处理。
- 每个 CloudBase 账号可免费创建 1 个环境（每月 3000 资源点）。

如何安装此技能？

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