社区/学习指南/小程序·云开发高级教程

CloudBase CLI

CloudBase CLI 是一个开源的命令行界面交互工具,用于帮助用户快速、方便的部署项目,管理云开发资源。有了这个工具,我们就能在电脑本地管理小程序云开发、Web 端云开发创建的环境,对环境里的云函数、云存储、云数据库进行增删改查等操作。

14.2.1 CLI 工具安装与登录

1、安装 Cloudbase CLI 工具

在本地电脑安装好了 Node 环境之后,我们可以打开电脑终端(Windows 电脑为 cmd 命令提示符,Mac 电脑为终端 Terminal),然后逐行输入并按 Enter 执行下面的代码就可在电脑里安装 CloudBase Cli 工具:


npm install -g @cloudbase/cli

cloudbase -v

-g是全局安装的意思,可能会出现权限不够的提示,如果是 Mac 电脑可以在前面加一个 sudo,而 Windows 可以通过管理员的方式打开 cmd 命令提示符。

安装完成后,你可以使用 cloudbase -v验证是否安装成功,如果输出了版本号,则表明 CloudBase CLI 被成功安装到您的计算机中。

2、CLI 工具登录与登出

要让 Cloudbase Cli 工具登录,首先我们打开腾讯云云开发控制台,选择微信公众号的方式来登录,扫描选择你的小程序账号,这样就可以进入管理控制台查看到你在开发者工具创建的云开发环境了。

在终端中输入下面的命令,CLI 工具会自动打开云开发控制台获取授权,在控制台的网页上点击同意授权按钮允许 CloudBase CLI 获取授权。登录成功后,在终端就会有登录成功的提示,并附带一些操作的 tips,这些操作的 tips 我们以后会用到。


cloudbase login

而要登出命令行工具 CloudBase CLI 的账号则可以使用 cloudbase logout

Cloudbase CLI 还有一种获取授权并登陆的方式,就是使用腾讯云的 API 密钥授权。首先到腾讯云官网获取云 API 密钥新建密钥,然后输入以下命令并按提示输入密钥的 SecretId 和 SecretKey 就可以完成登录:


cloudbase login --key

通过这种方式可以操作名下的所有腾讯云资源,因此注意要妥善保存和定期更换密钥,旧秘钥要及时删除。这种方式主要用于环境的批量管理。

3、了解 CloudBase Cli 命令

几乎所有的命令行工具,都支持--help的方式输出帮助信息来查看命令行主要支持哪些命令,这样我们就没有必要死记硬背命令了,直接通过这种方式来查看即可。


cloudbase --help

打印之后我们就可以看到 CloudBase Cli 除了我们前面的查看版本、登录腾讯云账号、输出帮助信息等命令外,还有很多命令并予以了一个简单的注解,有了这些命令我们就能对 CloudBase Cli 工具有了一些非常全面的了解了。比如我们想查看我们的账号下的环境信息,通过帮助信息了解到可以在终端输入以下命令即可:


cloudbase env:list

14.2.2 创建云开发项目

1、初始化环境

要如何在本地电脑与云开发的环境建立联系呢?就需要我们在电脑本地初始化环境。在电脑的 C 盘(Windows)或电脑的下载文件夹(Mac)里新建一个文件夹比如 tcbweb,然后在终端里输入以下命令进入到该目录,


#Windows 电脑

cd /d C:\download\tcbweb

# Mac电脑

cd downloads/tcbweb

然后再在终端输入以下命令来创建项目:


cloudbase init

这时会需要选择环境输入项目名称开发语言云开发模板,我们可以通过键盘的上下键来选择,开发语言要选择Nodejs(云开发也支持 PHP、Java),模板可以选择Hello World(也可以视情需求选择其他模板),确认之后项目就可以创建好了。

2、云开发项目

使用 cloudbase init 初始化项目时, CloudBase CLI 根据你输入的项目名称创建一个文件夹,并写入相关的配置和模板文件,创建的项目文件结构如下所示:


.

├── _gitignore

├── functions // 云函数目录

│   └── app

│       └── index.js

└── cloudbaserc.js // 项目配置文件

所有 CloudBase CLI 命令均在配置文件 cloudbaserc.js 所在目录执行,也就是说要在终端运行 Cloudbase CLI 命令,需要先进入 cloudbaserc.js 所在的目录,cloudbaserc.js 在哪里,哪里就是这个项目的根目录。建议编辑代码时使用编辑器比如 Visual Studio Code 或 IDE 工具 Webstrom 之类的,打开创建好的项目文件夹 tcbweb,这样方便运行、调试、编辑。

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

3、CLI 配置文件

配置文件可以简化 CloudBase CLI 使用,方便项目开发,当使用命令参数缺省时,CloudBase CLI 会从配置文件中解析相关参数并使用,方便开发者以更简单的方式使用 CloudBase CLI。

默认情况下,使用 cloudbase init 初始化项目时,会生成 cloudbaserc.js 或 cloudbaserc.json 文件作为配置文件,你也可以使用 --config-file 指定其他文件作为配置文件,文件必须满足格式要求。


{

  "envId": "dev-xxxx",             // 关联环境 ID

  "functionRoot": "functions",     // 云函数文件夹名称,相对路径,可以省略 './

  "functions": [                   // 云函数配置

    {

      "name": "app",           // functions 文件夹下函数文件夹的名称,即函数名

      "config": {              // 云函数配置

        "timeout": 5,        // 超时时间,单位:秒 S

        "envVariables": {    // 环境变量

            "key": "value"

        }

      }

    }

  ]

}

在 CLI 配置文件 cloudbaserc.js 中,functions 是一个数组,可以包含多个函数配置项,函数配置项包含了函数名称(name),函数运行配置(config),函数调用传入参数(params)等多项与函数相关的信息,影响着函数操作的行为表现,更多具体的配置比如私有网络、触发器等可以去参考相关技术文档。


{

  envId: 'dev-xxxx',       // 关联环境 ID

  functions: [      // 函数配置

    {

      name: 'app',          // functions 文件夹下函数文件夹的名称,即函数名

      config: {            // 函数配置

        timeout: 5,        // 超时时间,单位:秒 S

        envVariables: {

          key: 'value'      // 环境变量

        },

        vpc: {                  // 私有网络配置,如果不使用私有网络,可不配置

          vpcId: 'vpc-xxx',     // vpc id

          subnetId: 'subnet-xxx'  // 子网 id

        },

        runtime: 'Nodejs10.15',  // 运行时,目前可选运行包含:Nodejs8.9, Nodejs10.15,Php7, Java8等,默认为Nodejs 10.15

        installDependency: true   // 是否云端安装依赖,仅支持 Node.js 项目

      },

      triggers: [          // 函数触发器

        {

          name: 'myTrigger',  // name: 触发器的名字

          type: 'timer',      // type: 触发器类型,目前仅支持 timer (即定时触发器)

          config: '0 0 2 1 * * *'   // config: 触发器配置,在定时触发器下,config 格式为 cron 表达式

        }

      ],

      handler: 'index.main',

      params: {},     // functions:invoke 本地触发云函数时的调用参数

      ignore: [        // 部署/更新云函数时忽略的文件

        '*.md',           // 忽略 markdown 文件

        'node_modules',     // 忽略 node_modules 文件夹

        'node_modules/**/*'

      ]

    }

  ]

}

14.2.3 使用 CLI 工具操作云函数

1、查看云函数信息

我们可以在终端输入以下命令列出所有云函数(一次只会列出前 20 条)并查看云函数的基本信息:


cloudbase functions:list

如果你的函数较多,需要列出其他的函数,你可以通过下面的选项指定返回的数据长度以及数据的偏移量,有点类似于通过 skip 来翻页了。


-l, --limit <limit>    返回数据长度,默认值为 20

-o, --offset <offset>  数据偏移量,默认值为 0


#返回前 10 个函数的信息

cloudbase functions:list -l 10

#返回第 3 - 22 个函数的信息(包含 3 和 22)

cloudbase functions:list -l 20 -o 2

如果想查看所有云函数的详情、某个云函数的详情或某个云函数的调用日志,可以在终端输入以下命令来获取:


# 查看具体某个云函数的详情,比如云函数名为login

cloudbase functions:detail login


# 查看配置文件中的所有云函数的详情,注意是配置文件cloudbaserc.js 中的云函数

cloudbase functions:detail


#查看云函数的调用日志,比如云函数名为login

cloudbase functions:log login

我们可以通过查看云函数的详情了解到云函数的运行环境、网络、触发器、修改时间以及具体的代码等等,这是让我们可以在电脑本地了解一个云函数的部署情况的非常重要的命令了。

2、触发云函数

你可以在本地通过 Cloudbase CLI 直接触发云函数,也就是直接调用在服务端的云函数,调用成功后,会直接返回和在云开发控制台一样的云函数调用日志。


# 比如触发login函数

cloudbase functions:invoke login


# 触发配置文件中的全部函数

cloudbase functions:invoke

3、下载云函数代码

如果我们想要修改我们在小程序云开发里创建的云函数,首先就需要下载云函数的代码以及它的依赖,默认情况下,函数代码会下载到 functionRoot 下(也就是项目根目录下的 functions 文件夹里),以函数名称作为存储文件夹。


cloudbase functions:download login

当然,你也可以指定函数存放的文件夹地址,函数的所有代码文件会直接下载到指定的文件夹中。这个就和微信开发者工具下载云函数是一样的。


cloudbase functions:download login ./subfile

这里的./subfile是指项目根目录下的 subfile 文件夹,如果你要指定的时候,需要先创建这个文件夹,建议最好是直接默认下载到 functionRoot 下。

4、更新与部署云函数

当我们修改完本地云函数的代码之后就需要把本地云函数的代码更新或部署上传到服务端,更新代码 update 只会更新函数的代码以及执行入口,不会修改函数的其他配置,比如下面是更新 login 云函数


cloudbase functions:code:update login

而使用部署代码命令 deploy 时,则会修改函数的代码、配置以及触发器等,比如下面命令部署上传 login 云函数,在部署上传云函数前建议将 login 云函数的配置写在 cloudbaserc.js 里:


cloudbase functions:deploy login

如果我们不指定函数的名称,Cloudbase CLI 会会更新或部署配置文件中的全部函数:


# 更新配置文件中所有函数的配置信息

cloudbase functions:config:update

# 部署配置文件中所有函数的配置信息

cloudbase functions:deploy

如果只是想更新配置文件中云函数的配置信息,可以使用以下命令,目前支持修改的函数配置包含超时时间 timeout、环境变量 envVariables、运行时 runtime,vpc 网络以及 installDependency 等选项。


# 更新 login 函数的配置

cloudbase functions:config:update login


# 更新配置文件中所有函数的配置信息

cloudbase functions:config:update

如果存在同名的云函数需要覆盖,可以在命令后附加 --force 选项指定 Cloudbase CLI 覆盖已存在的云函数。


cloudbase functions:deploy dev --force

5、运行云函数

Cloudbase CLI 支持在本地运行云函数,这个有点类似于微信开发者工具的本地调试云函数,运行云函数时默认以 index.main 作为函数执行入口。在本地运行云函数既可以通过云函数的路径运行,也可以通过函数名来运行。

注意,要运行云函数,Node 的依赖 wx-server-sdk(核心是服务端 SDK @cloudbase/node-sdk)是必不可少的,本地运行云函数,就需要在本地安装 wx-server-sdk,在云端运行就要在云端安装这个依赖,由于我们的云函数是从云端下载下来的,都已经带有 wx-server-sdk 依赖了,所以不需要安装,但是如果是自己创建的云函数就必须要了哦~

你可以使用 --path 选项指定函数入口文件的路径,直接运行云函数,比如下面的命令是执行 login 云函数


cloudbase functions:run --path ./functions/login

还可以使用 --name 选项指定需要运行的云函数,使用 --name 选项时,可以通过 cloudbaserc.js 配置文件执行函数执行入口


cloudbase functions:run --name login

6、删除函数

您可以通过下面的命令来删除指定云函数和配置文件中的所有云函数。


#删除 login 函数

cloudbase functions:delete login


#删除配置文件中的所有的函数

cloudbase functions:delete

14.2.4 使用 CLI 工具操作操作云存储

云存储是云开发为用户提供的文件存储能力,用户可以通过云开发提供的 CLI 工具、SDK 对存储进行操作,如上传、下载文件。这里需要先了解一下 localPath 和 cloudPath 的概念。

  • localPath 为本地文件或文件夹的路径,为 目录/文件名 的形式,如 ./index.js(项目根目录下的文件)、static/css(项目根目录下的文件夹 static 文件夹里的 css 文件夹)。

  • cloudPath 为云存储文件或文件夹的相对根目录的路径,为 目录/文件名 的形式,如 cloudbase(云存储根目录下的 cloudbase 文件夹),cloudPath 不需要以 '/' 开头。

Windows 系统中 localPath 为本地路径形式,是系统可以识别的路径,通常使用\分隔符(Mac 电脑用/分隔符)。cloudPath 是云端文件路径,均需要使用 / 分隔符。

1、下载文件和文件夹

我们可以使用下面的命令来下载文件或文件夹,需要下载文件夹时,需要指定 --dir 参数。


# 下载文件

cloudbase storage:download cloudPath localPath


# 下载文件夹

cloudbase storage:download cloudPath localPath --dir

比如下面这段命令会将云存储根目录下的 cloudbase 文件夹里的文件下载到本地项目根目录下的 download 文件夹里(download 文件夹需事先创建),只要我们弄清楚了 cloudPath 和 localPath 的写法就能熟练使用这个命令了


cloudbase storage:download cloudbase ./download --dir

2、上传或删除文件/文件夹

我们可以使用下面的命令将本地电脑的文件或文件夹上传到云存储,当 CLI 检测到 localPath 为文件夹时,会自动上传文件内的所有文件,如果重复上传会覆盖。


cloudbase storage:upload localPath cloudPath

当不传入 cloudPath,文件会上传到云端的根目录下,同时文件夹的层次结构会被保留,比如下面的命令会把项目根目录的 download 文件夹里的内容直接上传到云存储的根目录里,download 的子文件夹会成为云存储的二级目录。


cloudbase storage:upload ./download

与之相应的,如果你想删除云存储里的文件或文件夹,可以使用下面的命令,需要删除文件夹时,需要指定 --dir 参数。


# 删除文件

cloudbase storage:delete cloudPath


# 删除文件夹

cloudbase storage:delete cloudPath --dir

3、了解云存储里的文件或文件夹信息

在不打开云开发控制台或网页控制台,我们也可以通过 Cloudbase Cli 工具了解云存储里的文件夹或文件的信息,比如在终端里输入以下命令可以列出云存储里的文件夹里的所有文件信息,比如大小、修改时间、key、Etag 等信息。


cloudbase storage:list cloudPath

比如我们可以直接使用以下命令打印云存储根目录里的所有文件(平时不要这么做,打印二级目录里的文件即可),其中二级目录里的文件会用路径的方式显示,比如 cloudbase/logo.png 表示是 cloudbase 文件夹下的 logo.png 图片。


cloudbase storage:list

如果我们想通过浏览器打开云存储里的文件,就需要获取文件临时访问链接。我们知道如果公有读的文件获取的链接不会过期,私有的文件获取的链接只有十分钟有效期。注意这里的 cloudPath 不能是文件夹,只能是文件哦


cloudbase storage:url cloudPath

比如我们想获取云存储 cloudbase 里的 logo.png 的临时访问链接,只需要在终端里输入以下命令:


cloudbase storage:url cloudbase/logo.png

我们还可以使用下面的命令获取文件的简单信息:


cloudbase storage:detail cloudPath

本文出自 李东bbsky