# 常见问题 FAQ
## CloudBase MCP 是什么？
云开发 CloudBase 是专为 AI Coding 提供的 **AI 原生后端服务**，通过 MCP 协议可以在 AI IDE 内一站式获得数据库、登录认证、云函数、容器托管、网站托管等后端集成和部署能力。换句话说，它把「云开发 CloudBase」变成了一个可以被 AI 直接调用的后端平台，让 AI 不止会写代码，还能帮你完成从数据存储、业务逻辑到上线部署的完整闭环。
CloudBase MCP 可以与多种 AI IDE 配合使用（例如 Cursor、WindSurf、CodeBuddy、Claude Code、GitHub Copilot 等），只需要简单配置一次 MCP，后续你就可以在这些 IDE 里用自然语言完成：
- 设计和创建数据库表、集合
- 管理文件存储、网站托管和静态资源
- 开发和部署云函数、云托管服务
- 一键完成前后端项目的构建和上线
## 选择 CloudBase 的原因
### 为什么选择 CloudBase？
- **极速部署**：国内节点,访问速度比海外更快
- **稳定可靠**：330 万开发者选择的 Serverless 平台
- **开发友好**：专为AI时代设计的全栈平台，支持自动环境配置
- **成本优化**：Serverless 架构更具弹性，新用户开发期间可以免费体验
## 开始使用
### 我是新用户，如何快速开始？
1. 安装支持的 AI 开发工具（如 Cursor、WindSurf 等）
2. 在腾讯云开发控制台开通环境（新用户免费）
3. 下载项目模板或在现有项目中配置 MCP
4. 对 AI 说"登录云开发"开始开发
### 支持哪些 AI 开发工具？
支持 CloudBase AI CLI、Cursor、WindSurf、CodeBuddy、CLINE、GitHub Copilot、Claude Code、Gemini CLI、OpenAI Codex CLI、OpenCode、Trae、通义灵码、RooCode、文心快码、Augment Code、Qwen Code、iFlow CLI 等主流 AI 开发工具。
## 技术问题
### 已有项目如何集成本模板和规则体系？
如果你已经有自己的项目，只需在配置好 MCP 后，对 AI 说 "在当前项目中下载云开发 AI 规则"，即可一键下载并补全 AI 编辑器规则配置到当前项目目录，无需手动操作。
如果你只想下载特定IDE的配置文件，避免项目文件混乱，可以指定IDE类型：
```
在当前项目中下载云开发 AI 规则，只包含Cursor配置
在当前项目中下载云开发 AI 规则，只包含WindSurf配置
在当前项目中下载云开发 AI 规则，只包含Claude Code配置
```
---
### 如何获取云开发环境 ID？
1. 访问 [腾讯云开发控制台](https://tcb.cloud.tencent.com/dev)开通环境，新用户可以免费开通体验
2. 在控制台「概览」页面右侧获取 **环境ID**
（后续部署需要此 ID）
---
### 如何更新 CloudBase AI ToolKit？
**更新 AI 规则**
如果你想在现有项目中更新到最新的云开发 AI 规则，只需对 AI 说：
```
下载云开发 AI 规则在当前项目中更新 rules
```
AI 会自动下载并更新最新的规则配置到你的项目目录。
**更新 MCP 工具**
当有新版本的 MCP 工具发布时，你可以通过以下方式更新：
1. **自动更新（推荐）**：在你的 AI 开发工具的 MCP 列表中，找到 cloudbase 并重新启用或刷新 MCP 列表即可自动安装最新版本
2. **手动更新**：如果自动更新不成功，可以先禁用再重新启用 cloudbase，或者重启你的 AI IDE
**注意事项**：
- MCP 配置中使用了 `@latest` 标签，通常会自动获取最新版本
- 如果遇到缓存问题，可以完全重启 AI IDE 后重新启用 MCP
- 建议定期检查更新以获得最新功能和修复
---
### MCP 显示工具数量为 0 怎么办？
如果在 AI 开发工具的 MCP 列表中看到 cloudbase-mcp 显示工具数量为 0，可以按以下步骤排查：
**1. 检查环境配置**
- 确保 Node.js 版本为 v18.15.0 及以上
- macOS 用户且使用 nvm 管理 Node.js 的，请务必设置默认 Node 版本为 v18.15.0 及以上，避免不同终端版本不一致导致的问题。
- 检查网络连接，建议设置 npm 源为腾讯镜像源：
```bash
npm config set registry https://mirrors.cloud.tencent.com/npm/
```
**2. 重新启用 MCP**
- 在 AI 开发工具的 MCP 列表中禁用 cloudbase-mcp
- 重新启用 cloudbase 或刷新 MCP 列表
- 如果仍有问题，完全重启 AI IDE 后重试
**3. 手动重新安装**
一般情况下，在 MCP 列表中重新启用或刷新即可正常安装并显示工具。
参考下方的 如何全局安装 CloudBase MCP？ 的步骤进行操作
---
### MCP 配置后提示 MCP error -32001: Request timed out
如果在配置 MCP 时遇到 `MCP error -32001: Request timed out` 错误，可以按以下步骤解决：
参考下方的 如何全局安装 CloudBase MCP？ 的步骤进行操作
### 如何全局安装 CloudBase MCP？
#### 遇到的问题
在使用 CloudBase MCP 时，你是否遇到过以下问题？
- **安装速度慢** - 使用 `npx` 每次都要重新下载，等待时间过长
- **配置复杂** - 需要手动配置 npm 源、Node.js 版本等环境依赖
- **重复安装** - 在不同 AI IDE 中需要重复配置 MCP 服务
- **网络问题** - npm 安装时经常遇到网络超时或下载失败
#### 解决方案：CloudBase AI CLI 快速安装
推荐使用 **CloudBase AI CLI** 的快速安装方式，一次性解决以下问题：
- 快速安装：相比 npm 安装通常需要几分钟，一键安装脚本只需几秒即可完成
- 统一管理：一个命令管理多种 AI 编程 CLI 工具，包括内置的 CloudBase AI Toolkit MCP
- 使用场景丰富：可在小程序开发者工具、VS Code、GitHub Actions 等环境中运行
- 开箱即用：安装完成后自动配置 MCP 服务，无需额外配置
#### 快速安装步骤
**1. 使用 npm 安装**
```bash
npm install @cloudbase/cli@latest -g
```
**2. 验证安装**
安装完成后，CloudBase AI CLI 会自动安装 CloudBase AI Toolkit MCP 服务，并生成全局命令 `cloudbase-mcp`。
**3. 配置 MCP**
重启你的 AI IDE，然后修改 MCP 配置：
```json
{
"mcpServers": {
"cloudbase": {
"command": "cloudbase-mcp"
}
}
}
```
**4. 验证 MCP 服务**
可以立即看到 CloudBase MCP 正常启动。
#### 支持的 AI IDE
CloudBase AI CLI 的快速安装方式适用于所有支持 MCP（Model Context Protocol）的 AI IDE，包括但不限于：
- **Cursor** - 基于 VS Code 的 AI 编程助手
- **WindSurf** - 腾讯云推出的 AI 编程工具
- **CodeBuddy** - 智能代码助手
- **Visual Studio Code** - 通过 CodeBuddy 插件支持
- **Claude Code** - Anthropic 的 AI 编程环境
- **GitHub Copilot** - 支持 MCP 的版本
- **其他支持 MCP 的 AI IDE**
这种统一的安装方式让你可以在不同的 AI IDE 之间无缝切换，无需重复配置。
- CodeBuddy中正常配置效果
- Visual Studio Code 中 CodeBuddy 插件配置 CloudBase MCP 正常效果
- Cursor 中正常配置效果
#### 了解更多
CloudBase AI CLI 不仅内置了 CloudBase AI Toolkit MCP，还支持多种主流 AI 编程工具：
- **Claude Code** - Anthropic 的 AI 编程助手
- **OpenAI Codex** - OpenAI 的代码生成工具
- **aider** - 开源的 AI 编程助手
- **Qwen Code** - 通义灵码
详细使用说明请参考：[CloudBase AI CLI 使用文档](/cli-v1/ai/introduce)
### MCP 配置不生效怎么办？
1. 检查配置格式是否正确
2. 重启 AI IDE
3. 确认 MCP 服务已启用
### Safari 浏览器无法完成授权登录怎么处理？
如果在使用 Safari 浏览器时遇到授权登录问题，建议切换到 Chrome 浏览器进行授权登录。
Safari 浏览器在某些情况下可能存在兼容性问题，影响授权流程的正常进行。Chrome 浏览器对云开发授权流程有更好的支持。
---
### 远程开发环境或服务端如何使用 MCP？
#### 遇到的问题
在远程开发环境中使用 CloudBase AI ToolKit 时，你是否遇到过这些挑战？
- **无法浏览器授权** - 服务器环境没有图形界面，无法完成浏览器登录
- **环境隔离** - 远程环境无法访问本地浏览器进行授权
- **自动化部署** - CI/CD 流水线中需要无交互的配置方式
- **权限管理** - 需要精确控制云开发资源的访问权限
#### 解决方案：环境变量配置
CloudBase AI CLI 支持通过环境变量进行无浏览器授权，完美解决远程环境的使用问题。
#### 安装 CloudBase AI CLI
```bash
npm install @cloudbase/cli@latest -g
```
安装完成后会自动生成 `cloudbase-mcp` 全局命令。
**配置方法：**
在 MCP 配置中使用 `env` 环境变量来设置认证信息：
```js
{
"mcpServers": {
"cloudbase": {
"command": "cloudbase-mcp",
"args": ["--integration-ide", "YOUR_IDE"],
"env": {
"TENCENTCLOUD_SECRETID": "腾讯云 SecretId",
"TENCENTCLOUD_SECRETKEY": "腾讯云 SecretKey",
"TENCENTCLOUD_SESSIONTOKEN": "腾讯云临时密钥Token，如果使用临时密钥才需要传入",
"CLOUDBASE_ENV_ID": "云开发环境 ID"
}
}
}
}
```
**获取密钥信息：**
- 腾讯云 SecretId 和 SecretKey：在 [腾讯云访问管理控制台](https://console.cloud.tencent.com/cam/capi) 获取
- 云开发环境 ID：在 [腾讯云开发控制台](https://tcb.cloud.tencent.com/dev) 概览页面获取
这种方式特别适用于：
- 远程开发环境（如 GitHub Codespaces、云 IDE 等）
- 服务端自动化脚本
- CI/CD 流水线中的自动化部署
---
### 支持哪些应用类型？
- **Web应用**：现代化前端 + 静态托管
- **微信小程序**：云开发小程序解决方案
- **后端服务**：云数据库 + 无服务器函数+云托管
---
### 开发微信小程序时有什么特别建议？
**推荐开发流程：**
1. **在微信开发者工具中开通云开发环境**
- 直接在微信开发者工具里开通，确保小程序与云开发环境完美绑定
2. **AI IDE 登录时选择【小程序/公众号】登录**
- 跳转登录腾讯云云开发时，选择【小程序/公众号】登录
- 使用你的小程序来登录，而不是腾讯云主账号
这样可以保证权限一致性，避免环境配置问题。
---
### 如何在微信开发者工具中使用 CloudBase AI ToolKit？
CloudBase AI ToolKit 与微信开发者工具可以完美配合使用，提供更高效的开发体验。
#### 方式一：从 AI IDE 开始开发
如果你已经在 AI IDE（如 Cursor、WindSurf、CodeBuddy 等）中开始开发小程序项目：
1. **AI IDE 开发**：在 AI IDE 中使用 CloudBase AI ToolKit 进行代码编写和云开发资源管理
2. **导入微信开发者工具**：在微信开发者工具中导入整个项目文件夹
3. **实时同步**：AI IDE 中的文件变化会实时同步到微信开发者工具
4. **构建预览**：在微信开发者工具中执行构建和预览操作
5. **错误排查**：如果遇到构建或运行错误，可以复制错误信息到 AI IDE 中进行智能排障
**优势：**
- 享受 AI 智能编程的便利
- 利用微信开发者工具的原生调试能力
- 实时预览和真机调试
- 完整的开发工具链
#### 方式二：从微信开发者工具开始
如果你已有微信开发者工具中的小程序项目：
1. **打开项目**：在 AI IDE 中打开现有的小程序项目文件夹
2. **配置 MCP**：参考文档配置 CloudBase MCP 服务
3. **下载 AI 规则**：对 AI 说"下载云开发 AI 规则"获取开发规则
4. **开始 AI 开发**：使用 AI 进行代码编写和云开发资源管理
5. **微信开发者工具预览**：在微信开发者工具中进行实时预览和调试
**工作流程：**
- AI IDE：负责代码编写、云函数开发、数据库设计等
- 微信开发者工具：负责小程序预览、真机调试、性能分析等
- 两者协同工作，发挥各自优势
**注意事项：**
- 确保两个工具打开的是同一个项目文件夹
- 文件保存后会自动同步，无需手动操作
- 建议在 AI IDE 中完成主要开发工作，在微信开发者工具中进行最终测试
---
## 环境管理
### 如何切换云开发环境？
```
退出云开发
登录云开发
```
### 如何切换腾讯云账号？
如果需要切换到不同的腾讯云账号：
1. **清理本地登录态**：对 AI 说 `退出登录`
2. **浏览器退出登录**：到浏览器里面退出原来登录的腾讯云账号
3. **重新登录**：对 AI 说 `登录云开发`
这样就可以切换到新的腾讯云账号了。
### 如何确认当前环境？
```
查询当前云开发环境信息
```
## 问题排查
### 部署失败了怎么办？
把完整的错误信息发给 AI：
```
报错了，错误是xxxx
```
### 云函数运行异常如何调试？
让 AI 查看日志并修复：
```
云函数代码运行不符合需求，需求是 xxx，请查看日志和数据进行调试，并进行修复
```
## 技术交流群
遇到问题或想要交流经验？加入我们的技术社区！
### 🔥 微信交流群
<div align="center">
<img src="https://7463-tcb-advanced-a656fc-1257967285.tcb.qcloud.la/mcp/toolkit-qrcode.png" width="200" alt="微信群二维码"/>
<br/>
<i>扫码加入微信技术交流群</i>
</div>
## 技术支持
### 遇到问题如何获取帮助？
1. 查看常见问题 FAQ
2. 在 [GitHub Issues](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit/issues) 提交问题
3. 加入微信技术交流群获取社区支持
### 如何参与社区？
- 加入微信技术交流群分享项目和交流经验
- 在 GitHub 上 Star 项目并提交 Issue 或 PR
- 关注官方文档获取最新功能更新
