# 云开发CloudBase实践总结从CLI到Framework一键部署

> 腾讯云开发 CloudBase 的完整实践笔记，覆盖 CLI 脚手架、云函数配置与触发器、静态网站托管、六种登录鉴权方式、CloudBase Framework 一体化部署插件、VS Code Toolkit、CMS 内容管理与 NoSQL 数据库接入。

- 原文：https://feinterview.poetries.top/blog/cloudbase-summary
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2022-06-25
- 可见范围：免费部分

---

做一个小工具站，后端只有六七个接口，结果卡住我最久的不是接口逻辑，是买机器、配 nginx、申请证书、写 PM2 守护、再折腾一遍 CI。真正写业务的时间可能只占三分之一，剩下三分之二全耗在跟业务无关的事情上。

腾讯云开发（CloudBase）想解决的就是这一段。它把云函数、云数据库、静态网站托管、登录鉴权这几样东西打包成一个环境，你只管写代码，剩下的构建、部署、扩缩容、HTTPS 都交给它。一条 `tcb framework deploy` 就能把一个前后端都在里面的项目推上去。

这篇是我把 CloudBase 从 CLI 装起、一路用到 Framework 一键部署、CMS 和 VS Code 插件的完整记录。内容偏长，是按「查手册」的思路组织的，你可以直接跳到你要用的那一节。中间标了几个真的卡住过我的地方，比如环境区域选错导致项目找不到、Node SDK 那几个「非必填」参数其实必填、CMS 本地开发的跨域。

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

- 云开发和 Serverless Framework 到底差在哪，什么项目该选哪个
- 控制台建环境，以及区域选错之后为什么项目会「消失」
- CLI 脚手架从安装、登录到 `tcb new` 建项目的全流程
- 环境管理，安全域名和登录方式怎么用命令行配
- `cloudbaserc.json` 的每一个配置项，以及动态变量和多环境切换
- 云函数的部署、触发器、Cron 表达式、日志和版本
- 静态网站托管的全量部署、增量删除和文件列表
- 六种登录鉴权方式的开通流程和完整代码，匿名、未登录、邮箱、微信、自定义、用户名密码、短信
- CloudBase Framework 的插件体系，website / function / node / container / database / auth / mp 七个插件
- 用 Framework 部署 Egg、Koa、React、Vue、Hexo 五种项目的实际配置
- 在云函数里连 NoSQL 数据库，`secretId` 和 `secretKey` 从哪拿
- VS Code Toolkit 插件的本地开发与调试
- CloudBase CMS 的控制台安装、源码二次开发、微应用接入和 RESTful API 鉴权

先说一句时效性。这篇写于 2022 年，这几年云开发控制台改版过不止一次，截图里的入口位置、按钮文案跟你现在看到的界面可能对不上。命令行和 SDK 这部分变动小得多，基本还能照着跑；控制台操作以你实际看到的界面为准，别死抠截图。

## 一、关于云开发介绍

刚接触的时候我一直分不清云开发和 Serverless Framework，觉得两个都是「不用管服务器」的东西。后来实际用下来才发现，它俩解决问题的层次不一样。

**云开发与serverless的区别**

- `Serverless Framework` 是无服务器应用框架，提供将云函数` SCF`、`API` 网关、对象存储 `COS`、云数据库 `DB` 等资源组合的业务框架，开发者可以直接基于框架编写业务逻辑，而无需关注底层资源的配置和管理。
- 云开发（`Tencent CloudBase，TCB`）是腾讯云提供的云原生一体化开发环境和工具平台，为开发者提供高可用、自动弹性扩缩的后端云服务，包含计算、存储、托管等 `serverless` 化能力，可用于云端一体化开发多种端应用（小程序、公众号、`Web` 应用、`Flutter` 客户端等），帮助开发者统一构建和管理后端服务和云资源，避免了应用开发过程中繁琐的服务器搭建及运维，开发者可以专注于业务逻辑的实现，开发门槛更低，效率更高。
- **二者最大的区别是**：给开发者使用的平台支持不一样，云开发支持web端、QQ、微信小程序级静态网站托管等这些平台服务。

我自己的理解是这样：Serverless Framework 更像一个「资源编排器」，它帮你把腾讯云上散落的 SCF、API 网关、COS 拼起来，你还是在跟一个个云产品打交道。云开发是把这些产品重新打包成一个叫「环境」的东西，环境里天生就有数据库、存储、云函数、静态托管和一套用户体系，多端 SDK 也是现成的。

所以选型的判断标准不是「哪个更 Serverless」，而是你的应用要跑在哪。要接小程序、公众号、H5 这些微信生态的端，云开发的多端 SDK 和登录鉴权能省掉大量胶水代码；要做的是一个纯粹的后端服务、需要精细控制每一个云资源，Serverless Framework 的自由度更高。

顺着上面聊，如果你的后端是一个完整的框架工程（Nest、Egg 这类），还有第三个选择是微信云托管，它直接跑容器。我在 [微信云托管入门与实践](https://feinterview.poetries.top/blog/wxcloud-intro) 里写过完整流程，跟这篇可以对照着看。

## 二、使用云开发创建一个nestjs项目

先从控制台走一遍最短路径，把环境建起来。后面所有的 CLI 操作都依赖这个环境 ID。

在产品中选择云开发产品

![腾讯云控制台产品列表中找到云开发 CloudBase 入口](https://s.poetries.top/uploads/2022/06/97bfb6a300ede8cb.png)

> 创建一个项目, 这里要选择好区域，下次创建了项目，区域不一样，可能项目就看不到

这个坑我踩得挺实在。云开发的环境是按地域隔离的，控制台顶部有个地域选择器，上海和广州是两套完全独立的列表。我第一次建在上海，第二天进来控制台默认切到了广州，列表空空如也，还以为环境被删了。后来发现只是地域没对上。

所以建环境之前先想清楚放哪个地域，记下来，后面 `cloudbaserc.json` 里的 `region` 字段填的就是它。上海地域可以不填，其他地域必填，这个规则后面第三节还会再提一次。

下面几张图是创建环境的完整流程，从选择计费方式、填环境名称，一直到环境创建完成后的概览页。

![云开发控制台点击新建环境的入口](https://s.poetries.top/uploads/2022/06/4a9fa09df00ae121.png)
![填写环境名称并选择计费方式的表单](https://s.poetries.top/uploads/2022/06/f91fc2a56fd7d19f.png)
![确认环境配置信息并提交创建](https://s.poetries.top/uploads/2022/06/111082e4a79965b8.png)
![环境正在初始化中的等待界面](https://s.poetries.top/uploads/2022/06/3cae71f70a9723d2.png)
![环境创建完成后的概览页，可以看到环境 ID 和各项资源用量](https://s.poetries.top/uploads/2022/06/4cccec9f4013b9aa.png)

最后那张概览页上的环境 ID 是你后面最常用的东西，形如 `xxx-9g9512mcxxxxxxx`，CLI、SDK、配置文件全都要它。建议直接复制出来存到笔记里。

关于计费方式还得多说一句：静态网站托管只有按量计费的环境能开通，预付费（包年包月）环境开不了。后面第九节的 CMS 也一样要求按量计费。要是你打算用这两个功能，建环境的时候就把计费方式选对，免得回头重建。

## 三、使用脚手架的方式创建

控制台点点点适合第一次摸清楚有哪些功能，日常开发还是得靠命令行。CloudBase CLI 能干的事情比控制台多，而且能写进脚本、进 CI，这一节把它的常用命令过一遍。

### 3.1 安装

全局安装脚手架包[官方地址](https://docs.cloudbase.net/cli-v1/quick-start)

```
npm i -g @cloudbase/cli
```

> 为了简化输入，cloudbase 命令可以简写成 tcb

本文后面全部用 `tcb` 这个短命令，你看到的 `cloudbase xxx` 和 `tcb xxx` 是同一个东西。

装完先验证一下，别等到部署失败了才回头查是不是没装上。

测试安装是否成功

```
tcb -v
```

查看命令

```
tcb -h
```

`tcb -h` 输出的那一大坨子命令值得扫一眼，`fn`、`env`、`hosting`、`framework` 这四个是后面用得最多的，分别管云函数、环境、静态托管和一键部署。

### 3.2 登录

CLI 要操作你账号下的资源，第一步得拿到授权。默认是交互式登录。

```
# CloudBase CLI 会自动打开云开发控制台获取授权，您需要点击同意授权按钮允许 CloudBase CLI 获取授权。如您没有登录，您需要登录后才能进行此操作。

tcb login
```

也可以使用下面的方式通过 API 秘钥直接登录，避免交互式输入

```
tcb login --apiKeyId xxx --apiKey xxx
```

这里有个坑要注意。`tcb login` 会拉起浏览器，在 CI 环境或者远程 SSH 的机器上根本没法完成，所以放到流水线里跑的时候必须用第二种密钥登录的方式。密钥在腾讯云访问管理的 API 密钥页面生成，别硬编码进仓库，走 CI 的 secret 变量注入。

### 3.3 创建项目

登录完就能建项目了。`tcb new` 会从官方模板拉一份骨架下来，省得自己从零搭。

本地创建项目

```bash
tcb new [options] [appName] [templateUri]
# 比如
tcb new nest-cloundbase nest-starter
```

> 云开发项目是和云开发环境资源关联的实体，云开发项目聚合了云函数、数据库、文件存储等服务，您可以在云开发项目中编写函数，存储文件，并通过 CloudBase 快速的操作您的云函数、文件存储、数据库等资源。

**云开发项目文件结构：**

```
.
├── .gitignore
├── functions // 云函数目录
│   └── node-app
│       └── index.js
└── cloudbaserc.json // 项目配置文件
```

这套目录结构的关键是 `cloudbaserc.json`。它是整个项目跟云端环境之间的唯一契约，CLI、VS Code 插件、云端一键部署读的都是它。第 3.5 节会把里面的每个字段拆开讲。

选择自己已经创建的环境,如果没有就 创建新环境,这时候会打开浏览器

![命令行提示选择关联的云开发环境](https://s.poetries.top/uploads/2022/06/6b018bec4591c9aa.png)

本地打开项目并且安装依赖包

```
npm install
npm run dev
```

部署到线上

```bash
# 调用 tcb framework deploy
npm run deploy
```

模板里的 `npm run deploy` 通常只是 `tcb framework deploy` 的一层封装，两者等价。部署过程中终端会滚出构建日志和资源创建日志，出错的话第一时间看这里，比去控制台翻要快。

![执行部署命令后终端输出的构建与上传过程](https://s.poetries.top/uploads/2022/06/c9016bdd4a84dac4.png)
![部署成功后终端打印出的访问地址和资源清单](https://s.poetries.top/uploads/2022/06/00b5a9d585e5f5ee.png)

部署完成后可以使用 `tcb fn list` 命令查看已经部署完成的函数列表

![tcb fn list 输出的云函数列表，含运行时和更新时间](https://s.poetries.top/uploads/2022/06/d83d3bfc9b7d025b.png)

到这一步，一个 Nest 项目就已经跑在云上了，中间没有碰过一次服务器。这个设计是真的舒服。

### 3.4 环境

环境是云开发里最顶层的隔离单位，一个环境就是一整套独立的数据库、存储、函数和用户体系。做多套环境（开发、测试、生产）本质就是建多个环境 ID，配置文件里换一下就行。

**查看所有环境**

```
tcb env list
```

![tcb env list 输出的环境列表，含环境 ID、别名和套餐](https://s.poetries.top/uploads/2022/06/417413944366f8e2.png)

这个命令是排查「项目怎么不见了」的第一步。列表里没有你要的环境，八成就是地域切错了，回控制台顶部把地域换过来再看。

**安全域名**

> 当您需要在网页应用中使用云开发的身份验证服务时，您需要将您的网站的域名（发起请求的页面的域名）加入安全域名名单中。安全域名是云开发服务认可的用户请求来源域名，所有来自非安全域名名单中的请求都不会被响应。

这个东西是本地开发阶段最容易忘的一步。你在 `localhost:8080` 上调 `@cloudbase/js-sdk`，请求直接被拒，控制台看到跨域报错，第一反应是代码写错了，其实只是域名没进白名单。本地开发记得把 `localhost` 也加进去。

使用下面的命令查看所有配置的安全域名

```
tcb env domain list
```

![tcb env domain list 输出的已配置安全域名清单](https://s.poetries.top/uploads/2022/06/efa5ad40c4f22218.png)

新增安全域名

```
# 添加一个域名
tcb env domain create www.xxx.com

# 添加多个域名
tcb env domain create www.domain1.com/www.domain2.com/www.domain3.com
```

多个域名用 `/` 分隔，这个分隔符挺反直觉的，不是逗号也不是空格，第一次写很容易搞错。

删除安全域名

```
tcb env domain delete
```

![tcb env domain delete 交互式勾选要删除的安全域名](https://s.poetries.top/uploads/2022/06/0f6c3726e168a64b.png)

删除是交互式的，命令敲下去之后会列出现有域名让你勾，不用记完整域名。

**登录方式**

> 当您需要使用云开发的身份验证服务时，您需要配置您想使用的登录方式。目前云开发支持自定义登录、微信公众平台、微信开放平台登录等多种登录方式。

```
# 您可以使用下面的命令列出环境配置的登录方式列表，查看环境配置的登录方式，以及相关的状态。

tcb env login list
```

![tcb env login list 输出的登录方式列表及启用状态](https://s.poetries.top/uploads/2022/06/0afa72546600b36a.png)

您可以使用下面的命令新建登录方式：

```
tcb env login create
```

> 您需要选择配置的平台，登录方式状态，以及对应的 AppId 和 AppSecret，登录方式请选择启用。在添加方式时不会校验 AppId 和 AppSecret 的有效性，只有在请求时，AppId 和 AppSecret 才会被校验，所以请确保您添加的 AppId 和 AppSecret 是有效的。

「添加时不校验，请求时才校验」这句话得留心。你把 AppSecret 敲错一个字符，命令行会告诉你创建成功，等到用户真去登录的时候才会失败，而且报错信息不一定指得清楚。配完最好立刻拿真实账号走一遍登录流程验证。

![tcb env login create 交互式选择登录平台并填写 AppId 和 AppSecret](https://s.poetries.top/uploads/2022/06/14072565a7df9cfc.png)

修改登录方式

> 您也可以使用 `tcb env login update` 修改已经配置的登录方式，如切换启用状态，修改 AppId 和 AppSecret。

![tcb env login update 修改已配置登录方式的交互界面](https://s.poetries.top/uploads/2022/06/4c5a0f883f8093dd.png)

各种登录方式在客户端具体怎么调，第四节会一个一个展开写代码，这里先把服务端的开关配好。

#### 动态变量

写死在配置文件里的环境 ID 和密钥，只要项目一多环境就是灾难。动态变量就是为了把这些值抽出去。

> 在 `cloudbaserc.json` 中声明 `"version": "2.0"` 即可启用新的特性，新版配置文件只支持 JSON 格式

```js
// 动态变量特性允许在 `cloudbaserc.json` 配置文件中使用动态变量，从环境变量或其他数据源获取动态的数据。使用 `{{}}` 包围的值定义为动态变量，可以引用数据源中的值。如下所示
{
  "version": "2.0",
  "envId": "envId",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "{{variable}}"
    }
  ]
}
```

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/blog/cloudbase-summary
