Skip to content

unidocs-zh
unidocs-zh

DCloud / unidocs-zh

通知 3201
Star 106
Fork 814
unidocs-zh
unidocs-zh
提交 e05f5578 编写于 作者: W wanganxp
浏览文件
操作

分拆快速上手，新增运行和发行

上级 995ba7b0
显示空白变更内容
内联 并排
Showing with 736 addition and 698 deletion
docs/uniCloud/cf-functions.md
浏览文件 @ e05f5578
......@@ -110,7 +110,7 @@ db.collection('list').get()
- 云对象不适用的情况：
不是和uni-app客户端通信，比如需要云函数URL化后与非uni-app客户端通信（其他应用或服务器），比如云端定时运行的云函数。
不是和uni-app客户端通信，比如需要云函数URL化后与非uni-app客户端通信（其他应用或服务器），比如云端定时运行的云函数。（但云对象未来有计划支持URL化和定时任务）
**直观体验代码示例**
......@@ -267,7 +267,9 @@ errMsg用于存放具体错误信息，包括展示给开发者、终端用户
## uniCloud API列表
云函数支持js和nodejs的标准API，但除了标准API外，uniCloud扩展了一批新API，实际开发中更常用的是uniCloud的扩展API。见下：
云函数支持 js 和 nodejs 的标准API，如`console.log()`、`setTimeout()`，另见[nodejs官网](https://nodejs.org/en/docs/)。nodejs版本，详见[云函数运行环境](?id=runtime)
除了标准API外，云函数环境中内置了`uniCloud`对象，扩展了一批新API，实际开发中更常用的是uniCloud的扩展API。见下：
|API |描述 |
|-- |-- |
......@@ -280,16 +282,19 @@ errMsg用于存放具体错误信息，包括展示给开发者、终端用户
|uniCloud.getTempFileURL() |获取云存储文件的临时路径 [详情](uniCloud/storage?id=cloudgettempfileurl) |
|uniCloud.customAuth() |使用云厂商自定义登录，仅腾讯云支持[详情](uniCloud/authentication.md?id=cloud-custom-auth) |
|uniCloud.callFunction() |客户端调用云函数 [见下](uniCloud/cf-functions?id=clientcallfunction)；云函数中调用另一个云函数 [见下](uniCloud/cf-functions?id=callbyfunction) |
|uniCloud.httpclient |云函数中通过http连接其他系统 [见下](uniCloud/cf-functions?id=httpclient) |
|uniCloud.httpclient |云函数中通过http访问其他系统 [见下](uniCloud/cf-functions?id=httpclient) |
|uniCloud.sendSms() |发送短信，需添加扩展库 [详见](uniCloud/send-sms.md) |
|uniCloud.getPhoneNumber() |获取一键登录手机号，需添加扩展库 [详见](uniCloud/univerify.md?id=cloud) |
|uniCloud.init() |获取指定服务空间的uniCloud实例 [详见](uniCloud/concepts/space.md?id=multi-space) |
|uniCloud.logger |云函数中打印日志到uniCloud日志记录系统（非HBuilderX控制台）[详情](uniCloud/cf-logger) |
|uniCloud.logger |云函数中打印日志到uniCloud日志记录系统（非HBuilderX控制台）[详情](rundebug.md?id=uniCloudlogger) |
## 访问数据库
云函数中支持访问本服务空间下的、或经授权的其他服务空间下的，数据库。因内容较长，另见[文档](uniCloud/cf-database.md)
云函数中支持访问本服务空间下的、或经授权的其他服务空间下的，数据库。
- 使用 MongoDB 语法操作数据库，另见[文档](uniCloud/cf-database.md)
- 使用 JQL 语法操作数据库，另见[文档](uniCloud/jql-cloud.md)
## 访问其他HTTP服务@httpclient
......@@ -512,13 +517,112 @@ myCloud.uploadFile()
**注意**
- 本地开发一旦使用了 node12 的专用 api，上传云函数时必须在package.json里手动配置选择 node12 的运行环境。
之所以没有在云端默认统一使用 node12，是因为腾讯云 node12 的 return 策略有一些特殊情况，见下。
之所以没有在云端默认统一使用 node12，是因为腾讯云 node12 的 return 策略有一些特殊情况，[见下](?id=return)。
- 运行环境在云端云函数创建时设定，不可通过更新云函数来修改。
也就是第一次上传云函数的时候，package.json里配了什么，就是什么。如果需要修改，需先删除云端云函数，重新上传。
node版本可以在云函数的package.json文件的`cloudfunction-config->runtime`字段进行配置，详情参考：[云函数package.json](uniCloud/cf-functions.md?id=packagejson)
### return的策略
### 云函数冷启动、热启动@launchtype
基于云函数按需执行的特点, 函数在不被触发的时候, 计算资源是不被激活的。
当一个云函数初次被触发时，其完整过程如下：
1. severless实例化计算实例
2. 加载函数代码
3. 启动 node
4. 执行代码
函数被调用时，执行这些完整步骤的过程一般称作`冷启动`, 冷启动的耗时长于热启动，一般在一秒出头。
而如果函数实例和执行进程都被复用的情况下一般被定义为`热启动`, 热启动没有性能问题。
如果一个云函数实例长时间没有被再次调用，则该计算实例会被**回收**；后续再次调用该云函数时，就会再次触发云函数的**冷启动**。
不同云厂商的函数实例回收时间不同：
- 阿里云：15分钟内没有第二次访问的云函数，就会被回收
- 腾讯云：30分钟
直观的体验表现为：隔了很久不用的云函数，第一次用就会比较慢，然后立即访问第二次，则很快，毫秒级响应。
注：冷启动虽慢但也不会超过1.5秒，如超过1.5秒应该是云函数写的有问题或网络有问题。
两家云厂商仍然在优化冷启动问题。目前给开发者的建议是：
1. 使用clientDB可以减少遇到冷启动问题的概率
2. 非高频访问的云函数，合并到高频云函数中。也有的开发者使用单路由方式编写云函数，即在一个云函数中通过路由处理实现了整个应用的所有后台逻辑。参考[插件](https://ext.dcloud.net.cn/search?q=%E8%B7%AF%E7%94%B1&cat1=7&orderBy=UpdatedDate)。
但使用这种方式需注意平衡，如果业务代码太多，每次云函数请求产生的内存消耗也会不少。
3. 非高频访问的云函数，可以通过定时任务持续运行它（注意腾讯云可以使用这个方式完全避开冷启动，而阿里云的定时任务最短周期大于资源回收周期）
4. 阿里云支持配置云函数的单实例多并发，请参考：[单实例多并发](cf-functions.md?id=concurrency)
5. 腾讯云付费进行实例预留
### 云函数的无状态
因为存在冷热启动的差异，云函数中的全局变量就可能出现每次不一样的情况。也就是**云函数是无状态的**。
以如下代码为例，`count`作为全局变量，当多次调用该云函数时，可能会出现变量累加的情况（实例未复用时，每次返回0，若实例被复用，则可能返回1、2、3等各种意外情况）。所以不要这么使用。
```javascript
let count = 0;
module.exports = async (event) => {
return count++
//此示例为错误示例
//云函数实例未复用时，每次返回0
//若实例被复用，则可能返回1、2、3等各种意外情况
}
```
**require由于存在缓存，也存在同样的问题。尽量不要直接修改require返回的内容**
### 临时存储空间
云函数是运行在云端的代码，运行环境由云服务器弹性调配，这是和传统`Node.js`应用很大的区别。
换言之，云函数每次执行的宿主环境（可简单理解为虚拟机或服务器硬件）可能相同，也可能不同，因此传统`Node.js`开发中将部分信息存储本地硬盘或内存的方案就不再适合，建议通过云数据库或云存储的方案替代。
### 云函数中的异步行为
书写云函数时应注意`async`、`await`的使用，`nodejs`有内置模块`util`可以将符合`error-first`形式`callback`的函数转换为`promise`形式，[详情参考](https://nodejs.org/api/util.html#util_util_promisify_original)，比如以下示例：
```js
const {
promisify
} = require('util')
let testCallback = {
value: 'testCallbackValue',
echo: function(num, callback) {
setTimeout(() => {
// 第一个参数为error，第二个为返回值
callback(null, `${this.value}:${num}`)
}, 2000)
}
}
exports.main = async function() {
// num=2，不传入callback参数，callback会自动作为回调函数处理
let val = await promisify(testCallback.echo).call(testCallback, 2)
console.log(val)
return val
}
```
如果想在云函数内使用回调形式可以让云函数返回一个promise，如以下示例：
```js
exports.main = async function() {
return new Promise((resolve, reject) => {
setTimeout(() => {
resolve('some return value')
}, 1000)
})
}
```
### return的策略@return
- 阿里云 return 之后云函数立即终止，逻辑不会继续执行，包括 settimeout 或其他异步操作都会立即终止。
- 腾讯云 node8 return 之后也不会继续执行，但 node12 可以配置是否继续执行
......@@ -528,13 +632,17 @@ node版本可以在云函数的package.json文件的`cloudfunction-config->runti
**腾讯云因为按 GBS 对云函数计费，在 node12 时，尤其要注意，如果未有效终止云函数，会一直计费**
### 时区
- 云端的云函数中使用的时区是 `UTC+0`，而不是 `UTC+8`，在云函数中使用时间时需特别注意。云函数在HBuilderX本地运行时，时区则是电脑的时区，很可能是 `UTC+8`。建议使用时间戳，可以规避时区问题。
## 云函数配置
云函数除了代码，还有配置。在uniCloud web控制台可以配置；在HBuilderX项目中，云函数根目录的package.json也是存放配置的地方。
云函数除了代码，还有配置。在uniCloud web控制台可以配置；在HBuilderX项目中，云函数根目录的`package.json`也是存放配置的地方。
### 超时时间@timeout
阿里云非定时触发请求云函数最大只支持10秒的超时时间。定时触发最大支持600秒的超时时间
阿里云非定时触发请求云函数最大只支持10秒的超时时间。定时任务触发最大支持600秒的超时时间，一般用于跑批。
腾讯云最大支持900秒超时时间
......@@ -704,8 +812,24 @@ package.json内统一了腾讯阿里的配置，两个平台都需要配置为
- runtime参数（nodejs版本）仅可在创建云函数时生效，不可修改
### 云函数的数量、体积、冷启动的平衡
鉴于：
- 每个服务空间的云函数数量是有限的，阿里云是48个，腾讯云是9~149个，[详见](price.md)
- 每个云函数的体积限制是10M（含node_modules）
- 云函数有冷启动问题
## 使用cloudfunctions_init@init
基于以上情况，对开发模式有如下建议：
1. 一般不建议使用体积较大、依赖较深的node_modules。多使用DCloud官方或插件市场提供的库。
2. 优先使用clientDB，不占用云函数数量，也不用编写服务器代码。
3. 对云对象或云函数做适当的合并和拆解。
- 低频且对用户体验影响较大的操作不建议独立使用云函数，合并到高频云函数中。
- 控制好单个云函数体积，有的开发者喜欢使用[单路由云函数](https://ext.dcloud.net.cn/search?q=%E8%B7%AF%E7%94%B1&orderBy=WeekDownload&cat1=7)，整个服务空间就一个云函数。这也得根据实际情况，如果云函数体积超过6M也还是建议分拆。
- 用户体系方面，官方已经提供uni-id-co云对象，再搭配clientDB，常规业务就够了。有特殊需求可以再适度补若干云对象。不太会发生云函数数量不足的情况。
4. 必要时可以使用多个服务空间，跨服务空间使用
## cloudfunctions_init（已废弃）
`HBuilderX 2.9`版本，`uniCloud`提供了`cloudfunctions_init.json`来方便开发者快速进行云函数的初始化操作。
......@@ -787,99 +911,3 @@ cloudfunction-config说明如下
}
```
## 注意事项
### 云函数的启动模式（冷启动、热启动）@launchtype
基于云函数按需执行的特点, 函数在不被触发的时候, 计算资源是不被激活的。
当一个云函数初次被触发时，其完整过程如下：
1. 实例化计算实例
2. 加载函数代码
3. 启动 node
4. 执行代码
函数被调用时，执行这些完整步骤的过程一般称作冷启动, 冷启动的耗时长于热启动，一般在一秒出头。
而如果函数实例和执行进程都被复用的情况下一般被定义为热启动, 热启动没有性能问题。
如果一个云函数实例长时间没有被再次调用，则该计算实例会被回收；后续再次调用该云函数时，就会再次触发云函数的冷启动。
不同云厂商的函数实例回收时间，以及优化冷启动的建议，[参考](https://uniapp.dcloud.io/uniCloud/faq?id=%e4%ba%91%e5%87%bd%e6%95%b0%e8%ae%bf%e9%97%ae%e6%97%b6%e5%bf%ab%e6%97%b6%e6%85%a2%e6%80%8e%e4%b9%88%e5%9b%9e%e4%ba%8b%ef%bc%9f)
因为存在冷热启动的差异，云函数中的全局变量就可能出现每次不一样的情况。也就是云函数是无状态的。
以如下代码为例，`count`作为全局变量，当多次调用该云函数时，可能会出现变量累加的情况（实例未复用时，每次返回0，若实例被复用，则可能返回1、2、3等各种意外情况）。所以不要这么使用。
```javascript
let count = 0;
module.exports = async (event) => {
return count++
//此示例为错误示例
//云函数实例未复用时，每次返回0
//若实例被复用，则可能返回1、2、3等各种意外情况
}
```
**require由于存在缓存，也存在同样的问题。尽量不要直接修改require返回的内容**
### 临时存储空间
云函数是运行在云端的代码，运行环境由云服务器弹性调配，这是和传统`Node.js`应用很大的区别。
换言之，云函数每次执行的宿主环境（可简单理解为虚拟机或服务器硬件）可能相同，也可能不同，因此传统`Node.js`开发中将部分信息存储本地硬盘或内存的方案就不再适合，建议通过云数据库或云存储的方案替代。
### 云函数中的异步行为
书写云函数时应注意`async`、`await`的使用，`nodejs`有内置模块`util`可以将符合`error-first`形式`callback`的函数转换为`promise`形式，[详情参考](https://nodejs.org/api/util.html#util_util_promisify_original)，比如以下示例：
```js
const {
promisify
} = require('util')
let testCallback = {
value: 'testCallbackValue',
echo: function(num, callback) {
setTimeout(() => {
// 第一个参数为error，第二个为返回值
callback(null, `${this.value}:${num}`)
}, 2000)
}
}
exports.main = async function() {
// num=2，不传入callback参数，callback会自动作为回调函数处理
let val = await promisify(testCallback.echo).call(testCallback, 2)
console.log(val)
return val
}
```
如果想在云函数内使用回调形式可以让云函数返回一个promise，如以下示例：
```js
exports.main = async function() {
return new Promise((resolve, reject) => {
setTimeout(() => {
resolve('some return value')
}, 1000)
})
}
```
### 普通云函数的单路由开发模式
虽然官方推荐clientDB和云对象，但仍有部分开发者习惯单路由方式开发。
也就是不使用多个云函数，而是使用路由框架，在一个云函数内通过控制器、路由的方式编写服务器接口。插件市场有很多这类插件，[详见](https://ext.dcloud.net.cn/search?q=%E8%B7%AF%E7%94%B1&orderBy=WeekDownload&cat1=7)
### 其它
- 云端的云函数中使用的时区是 `UTC+0`，而不是 `UTC+8`，在云函数中使用时间时需特别注意。云函数在HBuilderX本地运行时，时区则是电脑的时区，很可能是 `UTC+8`。建议使用时间戳，可以规避时区问题。
docs/uniCloud/cloud-obj.md
浏览文件 @ e05f5578
......@@ -146,7 +146,9 @@ _注：以上例子仅用于方便初学者理解。实际开发中对于简单
2. 更精简的代码
3. 更少的协作成本（以及矛盾~）
4. 客户端调用时在ide里有完善的代码提示，方法参数均可提示。（传输json可没法在ide里提示）
5. 自动支持[uniCloud响应体规范](uniCloud/cf-functions.md?id=resformat)，方便错误拦截和统一处理
5. 默认支持[uniCloud响应体规范](uniCloud/cf-functions.md?id=resformat)，方便错误拦截和统一处理
注：目前云对象还不支持URL和定时触发，未来会补充
## 快速上手
......
docs/uniCloud/publish.md 0 → 100644
浏览文件 @ e05f5578
本地开发调试后，务必上传到uniCloud服务空间才能在现网生效。
发行分为云端资源发行和客户端发行。
## 云资源发行
各种云函数、DB Schema，都需要上传发行。
HBuilderX有多种发行方式
- 发行菜单
- 对uniCloud目录中各种文件点右键上传。快捷键是【Ctrl+u】
- 对uniCloud目录点右键，启动 uniCloud服务空间初始化向导
### 小程序中使用uniCloud的白名单配置@useinmp
各家小程序平台，均要求在小程序管理后台配置小程序应用的联网服务器域名，否则无法联网。
使用uniCloud后，开发者将不再需要自己购买、备案域名，直接将uniCloud的域名填写在小程序管理后台即可。
根据下表，在小程序管理后台设置request合法域名、uploadFile合法域名（如没有上传文件业务，可不设置）。下表的域名均为阿里云或腾讯云自有域名，并非DCloud所属域名。
|服务提供商 |request合法域名 |uploadFile合法域名 |download合法域名|
|:-: |:-: |:-: |:-:|
|阿里云 |api.bspapp.com |bsppub.oss-cn-shanghai.aliyuncs.com|需要从云存储下载文件的时候才需要配置，不同服务空间域名不同，可以在web控制台查看文件详情里面看到|
|腾讯云 |tcb-api.tencentcloudapi.com|cos.ap-shanghai.myqcloud.com |需要从云存储下载文件的时候才需要配置，不同服务空间域名不同，可以在web控制台查看文件详情里面看到|
**如果需要用uni.request请求云存储内的文件，需要将云存储域名（即上表中的download合法域名）配置到request合法域名内**
小程序开发工具的真机预览功能，必须添加上述域名白名单，否则无法调用云函数。模拟器的PC端预览、真机调试不受此影响。
如果遇到正确配置了合法域名但是依然报`url not in domain list`，请尝试删除手机上的小程序、清理小程序所在的客户端缓存、重启对应的小程序开发工具后重试
如果遇到`invalid ip xxx, not in whitelist`，请检查是否在小程序管理后台开启了域名白名单。如果没用到可以关闭，如果确认需要使用ip白名单，请开通腾讯云收费空间并使用[固定IP](uniCloud/cf-functions.md?id=eip)功能
**关于云函数本地调试服务在小程序中的使用**
HBuilderX内使用运行菜单运行到小程序时会连接本地调试服务，即使你运行之前就选择了连接云端云函数，小程序也会发送一条请求到本地调试服务检测调用云函数是本地还是云端。
**在开发模式下推荐直接忽略域名校验。**
即使在开发工具勾选了忽略域名校验，体验版与正式版不会忽略域名校验。**如果要发布`体验版`或`正式版`，请务必在HBuilderX内使用发行菜单。**
### H5中使用uniCloud的跨域处理@useinh5
H5前端js访问云函数，涉及跨域问题，导致前端js无法连接云函数服务器。处理方式如下：。
- 运行到H5端时，使用HBuilderX内置浏览器，可以忽略跨域问题（需 HBuilderX 2.5.10+）。
- 发行到H5端时，需要在uniCloud后台操作，绑定安全域名（在部署云函数的服务空间配置部署h5的域名作为安全域名），否则会因为跨域问题而无法访问。（在`cloudfunctions`目录右键可打开uniCloud后台）
> 注意跨域配置需要带上端口信息。例如：前端页面运行于：www.xxx.com:5001，跨域配置内配置：www.xxx.com不会对此页面生效，需要配置为：www.xxx.com:5001
**uniCloud后台跨域配置：**
<div align=center>
<img src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/uniCloud-add-domain.png"/>
</div>
- 如果运行时，想使用外部浏览器运行，方案如下：
* 方式1：在uniCloud web控制台绑定测试期的地址为安全域名，如配置：localhost:8080、192.168.0.1:8080（建议直接使用内置浏览器测试）
* 方式2：在外部浏览器安装跨域插件，详见：[https://ask.dcloud.net.cn/article/35267](https://ask.dcloud.net.cn/article/35267)。要跨域的地址，详见上述文档中小程序配置安全域名章节。
**注意**
`2021年9月16日`之前阿里云跨域配置不对云存储及前端网页托管生效，表现为云存储中图片绘制到canvas会[污染画布](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API/Tutorial/Using_images#Using_other_canvas_elements)，前端网页托管的网页不可在iframe中使用。
`2021年9月16日`之后阿里云跨域配置可以对前端网页托管生效，**仅对前端网页托管的自定义域名生效，不对默认域名生效，如何绑定自定义域名请参考：[前端网页托管绑定自定义域名](uniCloud/hosting.md?id=domain)**，设置之后可能需要几分钟才会生效。如果你在之前已经设置了跨域域名和前端网页托管的自定义域名，需要重新设置一次跨域域名才能生效。
## 客户端资源发行
### 前端网页托管
uniCloud支持前端静态网页托管，在HBuilderX中点发行菜单，生成H5，将生成的前端文件部署在uniCloud的前端网页托管内即可[详情参考](uniCloud/hosting.md)。
需要注意的是你仍在[uniCloud web控制台](https://unicloud.dcloud.net.cn) 配置H5安全域名。
### App升级中心
uniCloud通过云端一体的升级检测、管理端版本维护。[详见](upgrade-center.md)
### 应用统一发布页
app、小程序、web统一发布页面。[详见](uni-publish.md)
## cli发行
规模化的开发时，经常需要通过命令行发行，做持续集成。
HBuilderX提供了cli，[详见](https://hx.dcloud.net.cn/cli/README)
\ No newline at end of file
docs/uniCloud/quickstart.md
浏览文件 @ e05f5578
## 创建uniCloud项目
## 体验 hello uniCloud
- 在 [HBuilderX 2.5.8+](https://www.dcloud.io/hbuilderx.html) 新建项目，选择uni-app项目，并勾选`启用uniCloud`
- 在右侧选择服务供应商
Hello uniCloud，是一个示例，演示了 uniCloud 的各种能力。
<div align=center>
<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-a90b5f95-90ba-4d30-a6a7-cd4d057327db/9623d950-5652-493e-9e0f-7c9aa846f6f3.jpg"/>
</div>
### 体验示例
这个示例目前只发布了h5版本和Android app版。
Hello uniCloud部署了2套，分别连接uniCloud的阿里云版和腾讯云版。
- 对于老的uni-app项目，也可以对项目点右键，菜单中选择“创建uniCloud云开发环境”
- 新建uni-app项目的模板中，有一个`Hello uniCloud`项目模板，演示了各种云函数的使用。
- h5版地址（发布在uniCloud的前端网页托管上）
* Hello uniCloud 腾讯云版地址：[https://hellounicloud.dcloud.net.cn/tcb/](https://hellounicloud.dcloud.net.cn/tcb/)
* Hello uniCloud 阿里云版地址：[https://hellounicloud.dcloud.net.cn/#/](https://hellounicloud.dcloud.net.cn/#/)
uniCloud云开发环境创建成功后，项目根目录下会有一个带有云图标的特殊目录，名为“uniCloud”。（即便是cli创建的项目，云函数目录也在项目的根目录下，而不是src下）
由于该示例未适配pc宽屏，如使用pc浏览器打开地址，建议F12打开控制台，使用手机模式预览。
非uni-app项目也可以通过使用[云函数Url化](uniCloud/http.md)来享受云函数的带来的便利。
- apk地址（发布在uniCloud的云存储上）
* Hello uniCloud 腾讯云版地址：[apk下载](https://vkceyugu.cdn.bspapp.com/VKCEYUGU-1a10688c-0b30-4aaa-bbc1-7f4948cc562a/bdf452e4-3a0d-49cb-9a97-8e1aa6572758.apk)
* Hello uniCloud 阿里云版地址：[apk下载](https://m3w.cn/__uni__5c6d4e4)
## 目录结构@structure
### 运行 Hello uniCloud 源码
Hello uniCloud 的源码地址：[https://ext.dcloud.net.cn/plugin?id=4082](https://ext.dcloud.net.cn/plugin?id=4082)
1. 在 HBuilderX 新建项目界面，选择uni-app项目，选择 Hello uniCloud 项目模板。
- 初次体验推荐阿里云，因为腾讯云的开户流程更复杂。
- 推荐使用vue3版本，因为编译速度更快。但注意不支持低版本Android。
<div align=center>
<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-a90b5f95-90ba-4d30-a6a7-cd4d057327db/9623d950-5652-493e-9e0f-7c9aa846f6f3.jpg"/>
</div>
2. HBuilderX 会在项目创建后弹出 uniCloud初始化向导，根据向导部署
- 按照法律要求，开通云服务器需实名认证，如未认证请根据提示完成
- 创建一个服务空间，创建完成后回到向导刷新列表，选择这个服务空间（创建服务空间可能需要几十秒的时间，可以在web控制台查看是否创建完成。）
- 按照向导提示，将hello uniCloud项目下的云函数、数据库schema上传部署到服务空间，并执行db_init初始化数据库
<!-- 缺图 -->
**说明**
HBuilderX 3.0起目录结构做了调整如下：
- 第一次创建腾讯云服务空间时会为用户创建腾讯云账号并跳转到腾讯云实名界面，等待实名认证审核之后可以开通服务空间。若腾讯云实名认证提示身份证下已创建过多账户，则需要在腾讯云官网注销不用的账户。
- 每个开发者账户，腾讯云仅提供1个免费服务空间，最多可创建49个收费服务空间。阿里云最多可创建50个免费服务空间。
3. 运行 hello uniCloud项目
- 在运行菜单运行项目，浏览器、app、小程序均可。uniCloud项目是云端一体的，运行前端后控制台会同时出现前端和云端的控制台。
## 目录结构@structure
uniCloud云开发环境创建成功后，项目根目录下会有一个带有云图标的特殊目录，名为“uniCloud”。（即便是cli创建的项目，云函数目录也在项目的根目录下，而不是src下）
<pre v-pre="" data-lang="">
<code class="lang-" style="padding:0">
┌──uniCloud-aliyun 云空间目录，阿里云为uniCloud-aliyun,腾讯云为uniCloud-tcb
┌──uniCloud-aliyun 云空间目录，阿里云为uniCloud-aliyun，腾讯云为uniCloud-tcb。但HBuilderX项目管理器会隐藏显示后缀，只显示uniCloud
| |——— cloudfunctions 云函数目录
| | │───common 云函数公用模块目录 <a target="_blank" href="https://uniapp.dcloud.io/uniCloud/cf-common">详情</a>
| | | └──hello-common 云函数公用模块
......@@ -30,549 +55,127 @@ HBuilderX 3.0起目录结构做了调整如下：
| | | └──package.json 公用模块package.json
| | │───uni-clientDB-actions
| | │ └──new_action.js clientDB action代码 <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/clientdb?id=action">详情</a>
| | └───function-name 云函数目录
| | │──index.js 云函数代码
| | └───function-name 普通云函数目录
| | │──index.js 云函数入口代码
| | └──package.json 包含云函数的配置信息，如url化、定时设置、内存等内容 <a target="_blank" href="https://uniapp.dcloud.io/uniCloud/cf-functions?id=packagejson">详情</a>
| | └───object-name 云对象目录
| | │──index.obj.js 云对象入口代码
| | └──package.json 包含云对象的配置信息<a target="_blank" href="https://uniapp.dcloud.io/uniCloud/cf-functions?id=packagejson">详情</a>
│ └──database 云数据目录
│ │──validateFunction 数据库扩展校验函数目录
│ │ └──new_validation.js 扩展校验函数代码 <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/schema?id=validatefunction">详情</a>
│ │──db_init.json db_init.json初始化数据库文件，其中不再包含schema <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/hellodb?id=db-init">详情</a>
│ └──xxx.schema.json 数据表xxx的DB Schema <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/schema">详情</a>
│ └──xxx.schema.json 数据表xxx的 DB Schema <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/schema">详情</a>
根目录
</code>
</pre>
#### 注意：uniCloud目录是存放服务端文件的目录，他和前端代码在同一个项目下这里只是方便管理。在发行前端部分，比如打包app、小程序、h5的代码包里并不会包含uniCloud目录。
**注意**
- uniCloud目录是存放服务端文件的目录，它和前端代码在同一个项目下是为了方便管理。在发行前端部分，比如打包app、小程序、h5的代码包里并不会包含uniCloud目录。
- HBuilderX 3.0之前目录结构较老，没有uniCloud目录，根目录直接是cloudfunctions。不支持database和云对象，不推荐再使用老版。
HBuilderX 3.0之前版本目录结构如下：
<pre v-pre="" data-lang="">
<code class="lang-" style="padding:0">
┌──cloudfunctions-aliyun 云空间目录，阿里云为cloudfunctions-aliyun,腾讯云为cloudfunctions-tcb
| │───function-name 云函数目录
| | │──index.js 云函数代码
| | └──package.json 标准package.json
| │───common 云函数公用模块目录 <a target="_blank" href="https://uniapp.dcloud.io/uniCloud/cf-common">详情</a>
| | └──hello-common 云函数公用模块
| | │──index.js 公用模块代码
| | └──package.json 公用模块package.json
| │───uni-clientDB-actions
| │ └──new_action.js clientDB action代码 <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/clientdb?id=action">详情</a>
│ │───db_init.json 初始化数据库文件 <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/hellodb?id=db-init">详情</a>
│ └───cloudfunctions_init.json 云函数初始化文件 <a target="_blank" href="https://uniapp.dcloud.net.cn/uniCloud/cf-functions?id=init">详情</a>
│
根目录
</code>
</pre>
## 开发自己的第一个uniCloud项目
1. 创建uniCloud项目
## 创建和绑定服务空间
HBuilderX中新建项目，选择uni-app项目，并勾选`启用uniCloud`，在右侧选择服务供应商（腾讯云或阿里云）
项目环境建好后，需要为这个项目选择一个服务空间。如果开发者账户没有实名认证，首先需要实名认证（这是法定要求，也是阿里云、腾讯云等云服务商的要求）。
项目名称随意，比如 firstunicloud
一个开发者可以拥有多个服务空间，每个服务空间都是一个独立的serverless云环境，不同服务空间之间的云函数、数据库、存储都是隔离的。
2. 关联服务空间
注：目前腾讯云仅提供1个免费服务空间，最多可创建49个收费服务空间。阿里云最多可创建50个免费服务空间。
一个开发者可以拥有多个服务空间，每个服务空间都是一个独立的serverless云环境，不同服务空间之间的云函数、数据库、存储都是隔离的。
服务空间和手机端项目是多对多绑定关系。同账号下，一个项目可以关联到多个服务空间。一个服务空间也可以被多个项目访问。
对目录`uniCloud`点右键选择`关联云服务空间`，绑定之前创建的服务空间，或者新建一个服务空间。
- HBuilderX 3.0起版本，在云函数目录`uniCloud`右键菜单创建服务空间，会打开web控制台[https://unicloud.dcloud.net.cn](https://unicloud.dcloud.net.cn) 进行创建
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/b16f9740-4c05-11eb-8a36-ebb87efcf8c0.jpg"/>
</div>
3. 创建云函数/云对象
- HBuilderX 3.0之前版本，在云函数目录`cloudfunctions`右键菜单创建服务空间，会打开web控制台[https://unicloud.dcloud.net.cn](https://unicloud.dcloud.net.cn) 进行创建
`uniCloud`项目创建并绑定服务空间后，开发者可以创建云函数（云对象是云函数的一种，云函数可泛指普通云函数和云对象）。
<div align=center>
<img style="max-width:750px;" src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/create-space.png"/>
</div>
- 创建好服务空间后，HBuilderX 3.0起版本对目录`uniCloud`点右键（HBuilderX 3.0之前版本对目录`cloudfunctions`点右键），菜单中点击`选择云服务空间`，绑定你之前创建的服务空间。
**说明**
- 第一次创建腾讯云服务空间时会为用户创建腾讯云账号并跳转到腾讯云实名界面，等待实名认证审核之后可以开通服务空间。若腾讯云实名认证提示身份证下已创建过多账户，则需要在腾讯云官网注销不用的账户。
- 创建服务空间可能需要几十秒的时间，可以在web控制台查看是否创建完成。
- 一个应用，可以在[dev.dcloud.net.cn](https://dev.dcloud.net.cn)设置协作者（选择应用->设置项目成员），实现多人共同使用一个云服务空间。（需 HBuilderX 2.5.9+）。协作者可以在HBuilderX和web控制台中操作被授权的服务空间，除了删除服务空间，其他功能均可正常操作。授权其他用户访问的详细步骤请参考：[授权其他用户访问服务空间](https://uniapp.dcloud.net.cn/uniCloud/faq?id=collaborator)
- 多个项目可以复用一个服务空间，比如一个应用的用户端和管理端，在HBuilderX里可以创建成2个项目，但2个项目的服务空间可以指向一个，或者干脆把其中一个项目的服务空间绑定到另一个项目上，[详见](https://ask.dcloud.net.cn/article/37949)
## 创建云函数
`uniCloud`项目创建并绑定服务空间后，开发者可以创建云函数。
HBuilderX 3.0起版本请在`uniCloud/cloudfunctions`目录右键创建云函数
在`uniCloud/cloudfunctions`目录右键创建云函数/云对象
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/a18b3bb0-53d8-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
创建云函数后，生成一个目录，该目录下自动生成index.js，是该云函数的入口文件，不可改名。
创建云对象后，生成一个目录，该目录下自动生成index.obj.js，是该云对象的入口文件，不可改名。
HBuilderX 3.0之前版本在 `cloudfunctions` 目录右键创建云函数
<div align=center>
<img style="max-width:750px;" src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/unicloud-02.png"/>
</div>
创建后会以云函数名称为名生成一个特殊目录，该目录下自动生成index.js，是该云函数的入口文件，不可改名。如果该云函数还需要引入其他js，可在index.js入口文件中引用。
**注意**
- 不同项目使用同一个服务空间时，不可使用同名云函数，可以在uniCloud的web控制台手动删除重名云函数释放函数名。
- 在HBuilderX创建云函数时，如果新云函数与服务器上已存在同名云函数，会用新函数覆盖。
- 单个云函数大小限制为10M（包含node_modules）
- 云函数内使用commonjs规范，不可使用import、export，参考：[commonjs模块](http://nodejs.cn/api/modules.html#modules_modules_commonjs_modules)
## 编写云函数
云函数的语法，是在普通的Node.js基础上补充了uniCloud的专用API。可参考API开发文档编写，也可以直接新建项目时选择`hello uniCloud`模板体验。
HBuilderX为uniCloud开发提供了良好的语法提示和转到定义支持，对于代码中的API，选中并按下F1，也可以直接查看相应的文档。
如下为一个云函数示例
```javascript
'use strict';
const db = uniCloud.database()
exports.main = async (event, context) => {
//event为客户端上传的参数
const collection = db.collection('unicloud-test') // 获取表'unicloud-test'的集合对象
const res = await collection.limit(10).get() // 获取表中的10条数据，结果为json格式
return res // 返回json给客户端
};
```
## 运行和调试云函数@rundebug
编写云函数后，在项目管理器里右键点击该云函数的目录，在弹出菜单中可选择“本地运行云函数”、“上传部署云函数”、“上传并运行云函数”。
如果使用`HBuilderX 3.0.0`及以上版本还可以使用客户端连接本地云函数的方式，不同于上面三种，客户端连接本地云函数需要在运行起来的客户端对应的HBuilderX控制台上切换连接云端还是本地云函数，如下图
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/28f84f90-3f69-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
- 上传部署云函数：将云函数部署到uniCloud服务空间，不会运行。（快捷键Ctrl+u）
- 上传并运行云函数：先上传云函数，并在云端立即执行该云函数。在部署后同时运行，并打印日志出来。有延时，调试时不如本地运行云函数快捷。
- 本地运行云函数：在HBuilderX自带的node环境中运行选中的云函数。云函数连接的数据库和云存储，仍然在云端。（快捷键Ctrl+u）（从HBuilderX 2.8.1起支持）
- 客户端连接本地云函数：开启一个uniCloud本地服务，运行前端项目时在HBuilderX控制台可切换访问云端云函数还是本地云函数。（从HBuilderX 3.0.0起支持）
**模式差异**
**上传部署云函数**
云函数会被上传到服务空间，不会执行。如果要测试需使用客户端调用此云函数。
**上传并运行云函数**
云函数会被上传到服务空间，然后执行一次，可以在HBuilderX内uniCloud控制台看到结果及日志。如果有配置运行测试参数，会使用配置的参数调用云函数。
上传并运行使用的资源全部都是云端资源。包括云函数、数据库、云存储。
**本地运行云函数**
云函数不会被上传到服务空间，只在本地运行，可以在HBuilderX内uniCloud控制台看到结果及日志。
这是一种独立测试云函数的方法，如需要配置前端参数，则需配置json文件，[详见](/uniCloud/quickstart?id=runparam)
本地运行时只有当前云函数会使用本地的。如果在当前云函数内使用callFunction调用其他云函数会调用云端已部署的云函数，云存储、数据库均会使用云端数据。
**客户端连接本地云函数**
云函数不会被上传到服务空间，由本地调试服务调用云函数，可以在HBuilderX内uniCloud控制台看到结果及日志。
这是一种前后端联调的方法，可较大提升联调效率。
使用clientDB操作数据库时，表结构（schema.json文件）、扩展校验函数、clientDB-actions均使用本地项目下的代码，但所操作的数据依然是云端数据，索引也是以云端为准。
客户端连接本地云函数时云函数内的callFunction也会调用本地云函数，除非目标云函数是插件市场售卖的加密云函数，此时仍会调用云端。
虽然云函数、数据库schema、validatefunction在本地了，但云存储、数据库的数据和索引，仍然在云端。也就是开发机不能纯脱线开发。
**注意**
- HBuilderX 3.0.0版本云函数目录有调整，请参考：[目录结构说明](uniCloud/quickstart.md?id=structure)
### 上传并运行云函数@uploadandrun
在项目管理器里右键点击云函数的目录，在弹出菜单中可选择“上传并运行云函数”。此外也可以打开此目录下的文件然后使用快捷键`Ctrl+r`，在弹出菜单中选择“上传并运行云函数”。上传并运行时会自动带上配置的运行测试参数。
如需配置运行测试参数请参考：[配置运行测试参数](https://uniapp.dcloud.net.cn/uniCloud/quickstart?id=runparam)
### 客户端连接本地云函数@calllocalfunction
自`HBuilderX 3.0.0`起支持客户端连接本地云函数，由客户端访问本地调试服务调用云函数。方便前后端联调、方便schema联调。
> 小程序开发需要注意，开发期间应关闭域名校验来建立和本地调试服务的连接，切勿使用HBuilderX的运行菜单发布体验版以及线上版。体验版和最终上线的版本应该以发行模式进行编译。
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/04d44f25-ce5f-4b39-a221-6600a0b80417.jpg"/>
</div>
**虽然云函数、数据库schema、validatefunction在本地，但云存储、数据库的数据和索引，仍然在云端。也就是开发机不能完全脱线开发。只是代码可以在本地写，免上传就能联调。**
**使用方式**
运行客户端后可以在HBuilderX控制台切换是连接本地云函数还是云端云函数，如下图所示
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/28f84f90-3f69-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
**日志查看**
切换为本地云函数之后客户端的callFunction会直接调用cloudfunctions目录下的云函数。此时云函数的日志会在HBuilderX uniCloud控制台打印。如下图
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/b6f52050-3f7a-11eb-8a36-ebb87efcf8c0.jpg"/>
</div>
切换连接云端云函数还是本地云函数之后会在项目下的`.hbuilderx`目录创建一个`launch.json`文件。
一个典型的`launch.json`是如下形式的（无需手动创建此文件）
```js
{
"version": "0.0.1",
"configurations": [
{
"app-plus": {
"launchtype" : "local" // app平台连接本地云函数
},
"default": {
"launchtype" : "remote" // 未配置的平台连接云端云函数
},
"h5": {
"launchtype" : "remote" // h5平台连接云端云函数
},
"provider": "aliyun", // 如果项目仅关联一个服务空间无需此参数
"type": "uniCloud", // 标识此项配置为uniCloud配置，必填
"systemLog": false // 设置为false之后关闭云函数控制台的系统日志（主要是云函数入参、返回值，错误信息不会关闭）
}
]
}
```
**断点调试**
> HBuilderX 3.2.10 起支持
开启断点调试方式如下图所示，在HBuilderX内的uniCloud控制台点击虫子图标即可开启断点调试。
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/015ee94b-23af-4aa0-b39b-b788b010dc4d.jpg"/>
</div>
**注意事项**
- 虽然云函数、数据库schema、validatefunction在本地，但云存储、数据库的数据和索引，仍然在云端。也就是开发机不能完全脱线开发。只是代码可以在本地写，免上传就能联调。
- 连接线上环境时请记得上传本地的schema、validatefunction、action
- 切换云端、本地，无需重新运行客户端
- 不同平台可以有不同的配置。但同一平台，如安卓和iOS都是app-plus，则对应着同一个配置，或者两台安卓手机也只能有一个配置
- 客户端在每次发送云函数请求之前，会发送一条请求到本地调试服务，本地服务会根据当前用户选择来通知客户端该访问本地云函数还是云端云函数
- 客户端连接本地云函数时，云函数内的callFunction也会调用本地云函数。除非目标云函数是插件市场售卖的加密云函数，此时不会调用本地，仍会调用云端
- 如果云函数或云函数依赖的公共模块有加密（在插件市场销售），则会忽略本地配置，请求云端已部署的云函数。请留意控制台输出
- 发送clientDB请求时，如果使用了加密的action（在插件市场销售），当前请求会使用云端已部署资源而不是本地资源（包括schema、validateFunction、action），请留意控制台输出
- 如果项目内关联了两个服务空间，需要在`.hbuilderx/launch.json`内配置provider参数指定哪个服务空间使用本地调试
- 当前项目运行的所有客户端都停止运行时，对本项目的调试服务会关闭，已经运行到手机的客户端将无法连接本地云函数
- 在h5端network面板的会看到一些`Request Method: OPTION`的请求，这些是跨域预检请求，忽略即可。请参考：[HTTP 的 OPTIONS 方法](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods/OPTIONS)
- 云函数超时时间、运行内存配置，在本地调试时不会生效
- 目前不支持使用了腾讯云自定义登录的场景
- 开发小程序时如果想使用本地云函数进行调试，请开启小程序的忽略安全域名校验
- 如果在使用HBuilderX过程中切换了电脑网络后本地调试服务无法访问，则需要重启一次HBuilderX
- 小程序体验版无法连接本地服务，如果发布成小程序体验版请务必使用发行模式
### 本地运行云函数@runlocal
自2.8.1版本起HBuilderX支持云函数本地运行，调试云函数更加方便快捷。此外还可以方便批量导入数据及文件，不再受云函数超时限制。
**使用方式**
在项目管理器选择要本地运行的云函数，右键选择本地运行。或者打开这个云函数内的文件，按`ctrl+r`回车。
- 如果没有安装本地运行插件，按照提示安装即可
- 如需配置运行参数请参考：[配置运行测试参数](https://uniapp.dcloud.net.cn/uniCloud/quickstart?id=runparam)
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/cb5457a0-4b19-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
在云函数编辑器里，按`Ctrl+r`运行快捷键（或点工具栏的运行），可看到运行云函数的若干菜单。`Ctrl+r`然后回车或选`0`，即可高效的在控制台看到运行结果和日志输出。如下图所示：
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/723ec000-4b1a-11eb-b680-7980c8a877b8.jpg"/>
</div>
云函数目前无法断点debug，只能打印`console.log`看日志。
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/caddd2a0-4b1a-11eb-b680-7980c8a877b8.jpg"/>
</div>
如果该云函数/云对象还需要引入其他js，可在index.js入口文件中引用。
运行云函数时，如需要给云函数传参，除了在前端传参外，在调试阶段，可以通过配置json文件来传测试参数。
初学者，建议从云对象学起，比云函数更加简单直观。
在云函数对应的目录右键可以配置运行测试参数，如下图，选择之后会生成一个形如`${函数名}.param.json`的文件，此文件内容会在云函数`上传并运行`以及`本地运行云函数`时作为参数传入云函数内。详细用法可参考：[配置运行测试参数](https://uniapp.dcloud.net.cn/uniCloud/quickstart?id=runparam)
在本教程中，我们创建一个云对象名为 helloco。
**断点调试**
4. 给云对象编写方法
> HBuilderX 3.2.10 起支持
开启断点调试方式如下图所示，在运行菜单选择`调试运行-本地云函数`即可。
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/2bd8ba0b-1066-48e4-b8a3-ed6f671c2a4f.jpg"/>
</div>
### 断点调试本地云函数@debug
自HBuilderX 3.2.10起，本地运行云函数及客户端连接本地云函数支持断点调试
如何使用请参考：[本地运行云函数](uniCloud/quickstart.md?id=runlocal)、[客户端连接本地云函数](uniCloud/quickstart.md?id=calllocalfunction)
开启调试后会出现调试界面，如下图所示。和浏览器的调试功能类似，详情可以参考：[JavaScript调试器](https://developer.mozilla.org/zh-CN/docs/Learn/Common_questions/What_are_browser_developer_tools#javascript%E8%B0%83%E8%AF%95%E5%99%A8)
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/ed6120d4-2882-44b5-892f-f3fec8493e8b.jpg"/>
</div>
在调试文件的编辑器界面的行号处双击可以插入断点，也可以右键选择更多操作（添加/删除/禁用断点）
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/fda77798-3cb8-4aaa-8ac9-ba718520352e.jpg"/>
</div>
如需从调试界面切换回项目视图，可以在项目管理器底部点击按钮进行切换
<div align=center>
<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/9cc24dbe-cde9-4a82-8872-4803ada97298.jpg"/>
</div>
## 调用本地云函数注意事项@local-tips
**本章节注意事项包括本地运行云函数、客户端连接本地云函数**
**使用公用模块**
本地运行的云函数使用公用模块时需注意：
- 需要在云函数内执行`npm install ../common/xxx`安装公共模块，详细请参考[云函数公用模块](uniCloud/cf-common.md)
- 如果使用`HBuilderX 3.0.0`及以上版本，可以直接在云函数目录右键选择“管理公共模块依赖”进行公共模块的引入
- 如果使用到加密的公共模块则此云函数不可本地运行
- `HBuilderX 3.0.0`版本运行uniCloud项目时，uniCloud本地调试插件会自动进行云函数依赖安装（包括公共模块和package.json里面的其他依赖）
**时区问题**
uniCloud云端的云函数使用的时区是utc+0，本地运行时使用的是本机时间，中国一般是+8。在使用“时间戳”时两者没有差异，但如果要获取年、月、日、小时要注意时区的差异。
以下方式可以获取指定时区的年、月、日、小时，可以参考一下
打开helloco.obj.js，我们为它添加一个 sum 方法，逻辑就是接收传入a和b2个参数，返回求和结果。
```js
// 获取偏移后的Date对象，例如utc+x时offset就传x
function getOffsetDate (offset) {
return new Date(
Date.now() + (new Date().getTimezoneOffset() + (offset || 0) * 60) * 60000
)
}
// 获取utc+8的小时数
const hour = getOffsetDate(8).getHours()
// 获取时间戳无需使用此方式utc+0时间戳是与utc+8时间戳一致的
```
推荐使用`<uni-dateformat>`组件格式化显示日期，[详情](https://ext.dcloud.net.cn/plugin?id=3279)
**调用其他云函数**
“本地运行云函数”时云函数内callFunction会调用云端已部署的云函数
“客户端连接本地云函数时”云函数内callFunction会调用本地云函数
**数据与存储**
请务必注意云函数在本地运行时依然是连接的云端数据库与存储
云函数上传文件到云存储只有腾讯云支持。当然也可以在前端直接上传文件，此时阿里云腾讯云均支持。
**Nodejs版本**
服务空间所使用的nodejs版本为8.9，本地运行时使用的本地nodejs可能与服务空间的nodejs版本并不一致，在本地测试之后部署到云端也务必测试一下兼容性。
## 运行云函数时配置运行测试参数@runparam
在云函数的上传运行菜单或右键菜单中，有`配置运行测试参数`的功能。
可以打开一个json，配置运行参数。配置该json后，运行云函数时会将该json作为云函数调用的上行参数处理，可以在云函数中接收到参数。
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/37245420-4b1b-11eb-b997-9918a5dda011.jpg"/>
</div>
在云函数目录右键运行云函数，也可以在云函数编辑器里，按`Ctrl+r`运行快捷键，或点工具栏的运行
<div align=center>
<img src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/run-function-with-param-1.jpg"/>
</div>
此时云函数运行会携带所配置的运行参数
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/84352e10-4b1b-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
**模拟客户端类型**
如果需要模拟客户端类型可以在运行参数内添加clientInfo字段
```
{
"otherParam": "***",
"clientInfo":{
OS: "ios" // 系统类型 ios、android
PLATFORM: "h5" // 客户端类型 app-plus、h5、mp-weixin、mp-alipay等
module.exports = {
sum(a, b) {
// 此处省略a和b的有效性校验
return a + b
}
}
```
## 手机端调用云函数
在uni-app的前端代码中，通过`uniCloud.callFunction`方法调用云函数。详见[callFunction文档](https://uniapp.dcloud.io/uniCloud/cf-functions#clientcallfunction)
如下代码中，调用了名为`test`的云函数，并发送了`data`的json数据作为上行参数。
```javascript
// promise方式
uniCloud.callFunction({
name: 'test',
data: { a: 1 }
})
.then(res => {});
// callback方式
uniCloud.callFunction({
name: 'test',
data: { a: 1 },
success(){},
fail(){},
complete(){}
});
```
## 手机端看日志
5. 在前端调用云对象
uni-app运行在HBuilderX内置浏览器和App环境时，在HBuilderX的控制台中，除了可以看普通手机端日志外，还可以直接看到云端的云函数里打印的console.log日志。
在项目首页，pages/index/index.vue 里，添加一个按钮，点击后执行异步方法sum。
**示例**
js中import这个 helloco 对象，调用它的 sum 方法
所执行云函数代码
```html
<template>
<view class="content">
<button @click="testco()">请求云对象的方法</button>
</view>
</template>
```javascript
'use strict';
exports.main = async (event, context) => {
console.log('------------');
console.log('云函数日志输出');
console.log('------------');
<script>
export default {
data() {
return {
action: 'log demo'
}
};
},
methods: {
async testco() { // 注意异步
const helloco = uniCloud.importObject('helloco') // 导入云对象
try {
const res = await helloco.sum(1,2) //导入云对象后就可以直接调用该对象的sum方法了，注意使用异步await
console.log(res) // 结果是3
} catch (e) {
console.log(e)
}
}
}
}
</script>
```
H5端HBuilderX内置浏览器输出云函数日志，如下图所示（注意：日志在HBuilderX控制台输出）：
<div align=center>
<img src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/uniCloud-function-log-h5.jpg"/>
</div>
App端真机调试输出云函数日志，如下图所示：
<div align=center>
<img style="max-width:750px;" src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/uniCloud-function-log.png"/>
</div>
- 如运行到小程序开发工具或外部浏览器，仅能在这些软件的调试控制台查看本地日志，不包含云函数里的console.log。
uniCloud的[web控制台](https://unicloud.dcloud.net.cn/)可以查看线上云函数的所有运行日志，而不仅仅是开发时的运行日志。
## clientDB - 前端直接操作数据库
uniCloud支持云函数，但其实大多数场景下并不需要写云函数，可以通过clientDB直接操作云数据库。
1. 在HBuilderX中，uniCloud\database目录下编写数据表的schema文件。上传到uniCloud。
2. 在前端通过clientDB组件或api，直接读写数据表。
详细文档另见：[clientDB](https://uniapp.dcloud.io/uniCloud/database)
## 小程序中使用uniCloud的白名单配置@useinmp
各家小程序平台，均要求在小程序管理后台配置小程序应用的联网服务器域名，否则无法联网。
使用uniCloud后，开发者将不再需要自己购买、备案域名，直接将uniCloud的域名填写在小程序管理后台即可。
根据下表，在小程序管理后台设置request合法域名、uploadFile合法域名（如没有上传文件业务，可不设置）。下表的域名均为阿里云或腾讯云自有域名，并非DCloud所属域名。
|服务提供商 |request合法域名 |uploadFile合法域名 |download合法域名|
|:-: |:-: |:-: |:-:|
|阿里云 |api.bspapp.com |bsppub.oss-cn-shanghai.aliyuncs.com|需要从云存储下载文件的时候才需要配置，不同服务空间域名不同，可以在web控制台查看文件详情里面看到|
|腾讯云 |tcb-api.tencentcloudapi.com|cos.ap-shanghai.myqcloud.com |需要从云存储下载文件的时候才需要配置，不同服务空间域名不同，可以在web控制台查看文件详情里面看到|
**如果需要用uni.request请求云存储内的文件，需要将云存储域名（即上表中的download合法域名）配置到request合法域名内**
小程序开发工具的真机预览功能，必须添加上述域名白名单，否则无法调用云函数。模拟器的PC端预览、真机调试不受此影响。
如果遇到正确配置了合法域名但是依然报`url not in domain list`，请尝试删除手机上的小程序、清理小程序所在的客户端缓存、重启对应的小程序开发工具后重试
6. 运行
如果遇到`invalid ip xxx, not in whitelist`，请检查是否在小程序管理后台开启了域名白名单。如果没用到可以关闭，如果确认需要使用ip白名单，请开通腾讯云收费空间并使用[固定IP](uniCloud/cf-functions.md?id=eip)功能
将项目运行到浏览器或其他平台，点页面上的按钮，控制台会打印结果：3
**关于云函数本地调试服务在小程序中的使用**
HBuilderX自带一个云函数本地运行环境，运行项目时也默认选择 连接本地云函数。可以在底部控制台中的前端控制台右上角进行切换。
HBuilderX内使用运行菜单运行到小程序时会连接本地调试服务，即使你运行之前就选择了连接云端云函数，小程序也会发送一条请求到本地调试服务检测调用云函数是本地还是云端。
可以对helloco云对象点右键上传到uniCloud服务空间，然后在前端控制台右上角切换为 连接云端云函数，那么此时客户端连接的就是真正的现网uniCloud服务器了。
**在开发模式下推荐直接忽略域名校验。**
7. 小结
即使在开发工具勾选了忽略域名校验，体验版与正式版不会忽略域名校验。**如果要发布`体验版`或`正式版`，请务必在HBuilderX内使用发行菜单。**
到此为止，你已经开发了第一个 first uniCloud 项目，完成了客户端和服务器的第一次交互。
## H5中使用uniCloud的跨域处理@useinh5
这个云对象只做了一个求和运算，实际开发中不需要在服务器求和，前端就可以求和。服务器应该做更复杂的事情。
H5前端js访问云函数，涉及跨域问题，导致前端js无法连接云函数服务器。处理方式如下：。
但你可以通过这个示例感知uniCloud的开发，其实非常简单。尤其是云对象，打破了服务器做接口传json给前端的传统，让云端服务对象化，让服务器代码像写前端js一样、清晰。
- 运行到H5端时，使用HBuilderX内置浏览器，可以忽略跨域问题（mac版需2.5.10+）。
- 发行到H5端时，需要在uniCloud后台操作，绑定安全域名（在部署云函数的服务空间配置部署h5的域名作为安全域名），否则会因为跨域问题而无法访问。（在`cloudfunctions`目录右键可打开uniCloud后台）
接下来，建议通读文档，进一步学习掌握uniCloud。
> 注意跨域配置需要带上端口信息。例如：前端页面运行于：www.xxx.com:5001，跨域配置内配置：www.xxx.com不会对此页面生效，需要配置为：www.xxx.com:5001
**uniCloud后台跨域配置：**
<div align=center>
<img src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/uniCloud-add-domain.png"/>
</div>
- 如果运行时，想使用外部浏览器运行，方案如下：
* 方式1：在uniCloud web控制台绑定测试期的地址为安全域名，如配置：localhost:8080、192.168.0.1:8080（建议直接使用内置浏览器测试）
* 方式2：在外部浏览器安装跨域插件，详见：[https://ask.dcloud.net.cn/article/35267](https://ask.dcloud.net.cn/article/35267)。要跨域的地址，详见上述文档中小程序配置安全域名章节。
**注意**
`2021年9月16日`之前阿里云跨域配置不对云存储及前端网页托管生效，表现为云存储中图片绘制到canvas会[污染画布](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API/Tutorial/Using_images#Using_other_canvas_elements)，前端网页托管的网页不可在iframe中使用。
`2021年9月16日`之后阿里云跨域配置可以对前端网页托管生效，**仅对前端网页托管的自定义域名生效，不对默认域名生效，如何绑定自定义域名请参考：[前端网页托管绑定自定义域名](uniCloud/hosting.md?id=domain)**，设置之后可能需要几分钟才会生效。如果你在之前已经设置了跨域域名和前端网页托管的自定义域名，需要重新设置一次跨域域名才能生效。
## cli项目中使用uniCloud
......@@ -589,22 +192,16 @@ H5前端js访问云函数，涉及跨域问题，导致前端js无法连接云
- 运行与发行云函数只能使用HBuilderX的菜单，不可使用`package.json`内的命令
- 如果HBuilderX菜单运行不能满足需求可以考虑自行初始化服务空间[服务空间初始化](uniCloud/init.md)
**H5前端页面部署问题**
uniCloud支持前端页面部署，在HBuilderX中点发行菜单，生成H5，将生成的前端文件部署在uniCloud的前端网页托管内即可[详情参考](uniCloud/hosting.md)。
需要注意的是你仍在[uniCloud web控制台](https://unicloud.dcloud.net.cn) 配置H5安全域名。
**Tips**
- 虽然uni-app支持vscode等其他ide开发，但因为uniCloud对安全性要求极高，仅支持使用HBuilderX开发。
## web控制台@webcp
web控制台网址：[https://unicloud.dcloud.net.cn](https://unicloud.dcloud.net.cn)，在HX中对云函数目录点右键，或者在帮助菜单中，均有入口链接。
web控制台网址：[https://unicloud.dcloud.net.cn](https://unicloud.dcloud.net.cn)
在HX中对 uniCloud 目录点右键，或者在帮助菜单中，均有入口链接。
### 编辑数据库数据@editdb
### 编辑数据库数据注意事项@editdb
在web控制台可以对数据库进行编辑。在json文档中，输入字符串、数字、bool值都是常规的操作。但有2种特殊数据类型，时间和地理位置，在编辑时有特殊的写法，请注意：
......
docs/uniCloud/rundebug.md 0 → 100644
浏览文件 @ e05f5578
## 云函数/云对象运行方式介绍
云函数或云对象，在开发期间，可以在HBuilderX提供的本地环境运行，也可以连接现网uniCloud云端运行。
注意：本地运行环境只包括云函数和 `DB Schema`，数据内容必须在云端。因为本地运行环境没有MongoDB。
云函数/云对象可以自己直接在本地或云端的云函数环境里运行，也可以由uni-app客户端连接云函数，触发本地或云端的运行环境进行联调运行。
云对象属于云函数的一种，所以很多界面菜单或文档没有单独强调时，“云函数”将包含“云对象”。
所以总结一下，云函数有4种运行模式：
1. 本地运行
2. 上传云端并运行（云对象不支持此模式）
3. 客户端连本地云函数运行
4. 客户端连云端云函数运行
云函数/云对象可通过菜单或快捷键运行。
1. 右键菜单：在项目管理器里右键点击该云函数的目录，在弹出菜单中可选择“本地运行云函数”、“上传并运行云函数”
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/cb5457a0-4b19-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
2. 工具栏：编辑器打开云函数时，点击工具栏`运行`按钮，下拉菜单也有“本地运行云函数”、“上传并运行云函数”
3. 快捷键：编辑器打开云函数时，按【Ctrl+r】快捷键，会激活上述运行菜单。
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/723ec000-4b1a-11eb-b680-7980c8a877b8.jpg"/>
</div>
如果没有安装本地运行插件，按照提示安装即可。本地运行云函数需HBuilderX 2.8.1+
运行后将打开云函数控制台，在控制台看到运行结果和日志输出。
## 本地运行云函数@runlocal
> HBuilderX 2.8.1版本起支持
在HBuilderX的uniCloud本地运行插件的node环境中直接运行云函数或云对象。
**使用方式**
- 如果没有安装本地运行插件，按照提示安装即可
- 如需配置运行参数请参考：[配置运行测试参数](https://uniapp.dcloud.net.cn/uniCloud/quickstart?id=runparam)
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/cb5457a0-4b19-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
在云函数编辑器里，按`Ctrl+r`运行快捷键（或点工具栏的运行），可看到运行云函数的若干菜单。`Ctrl+r`然后回车或选`0`执行本地运行，即可立即在控制台看到运行结果和日志输出。如下图所示：
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/723ec000-4b1a-11eb-b680-7980c8a877b8.jpg"/>
</div>
云函数打印`console.log`看日志。
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/caddd2a0-4b1a-11eb-b680-7980c8a877b8.jpg"/>
</div>
运行云函数时，如需要给云函数传参，又不想启动客户端，那么可以通过配置json文件来传测试参数。
在云函数对应的目录右键可以配置运行测试参数，如下图，选择之后会生成一个形如`${函数名}.param.json`的文件，此文件内容会在云函数`上传并运行`以及`本地运行云函数`时作为参数传入云函数内。详细用法可参考：[配置运行测试参数](https://uniapp.dcloud.net.cn/uniCloud/quickstart?id=runparam)
## 上传并运行云函数@uploadandrun
在项目管理器里右键点击云函数的目录，在弹出菜单中可选择“上传并运行云函数”。此外也可以打开此目录下的文件然后使用快捷键`Ctrl+r`，在弹出菜单中选择“上传并运行云函数”。
对于云函数，上传并运行时会自动带上配置的运行测试参数。请参考：[配置运行测试参数](?id=runparam)
注：云对象不支持上传并运行。
## 客户端联调云函数@calllocalfunction
> `HBuilderX 3.0.0`起支持
运行含有uniCloud的uni-app项目，除了启动客户端控制台外，还会启动uniCloud控制台。
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/04d44f25-ce5f-4b39-a221-6600a0b80417.jpg"/>
</div>
可以在客户端控制台的右上角切换是连接本地云函数还是云端云函数，如下图所示
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/28f84f90-3f69-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
uniCloud控制台日志如下图：
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/b6f52050-3f7a-11eb-8a36-ebb87efcf8c0.jpg"/>
</div>
此时客户端的日志和云函数的日志都可以看到，联调非常方便。
注：小程序开发需要注意，开发期间应关闭域名校验来建立和本地调试服务的连接，切勿使用HBuilderX的运行菜单发布体验版以及线上版。体验版和最终上线的版本应该以发行模式进行编译。
**配置保存**
切换连接云端云函数还是本地云函数之后会在项目下的`.hbuilderx`目录创建一个`launch.json`文件。
一个典型的`launch.json`是如下形式的（无需手动创建此文件）
```js
{
"version": "0.0.1",
"configurations": [
{
"app-plus": {
"launchtype" : "local" // app平台连接本地云函数
},
"default": {
"launchtype" : "remote" // 未配置的平台连接云端云函数
},
"h5": {
"launchtype" : "remote" // h5平台连接云端云函数
},
"provider": "aliyun", // 如果项目仅关联一个服务空间无需此参数
"type": "uniCloud", // 标识此项配置为uniCloud配置，必填
"systemLog": false // 设置为false之后关闭云函数控制台的系统日志（主要是云函数入参、返回值，错误信息不会关闭）
}
]
}
```
## HBuilderX 本地uniCloud运行环境介绍@local-tips
HBuilderX 2.8.1+ 支持uniCloud本地运行插件。
不管是云函数直接本地运行，还是客户端连接本地云函数，都使用的是 uniCloud本地运行插件。
本地运行环境与uniCloud现网的差别：
1. 本地环境只有node运行环境
也就是云函数、DB Schema可以使用本地，但本地没有MongoDB、没有redis、没有云存储，数据内容仍然存放在uniCloud现网服务空间。数据库索引也在云端才生效。
2. node版本差异
本地运行的nodejs版本为node12。
服务空间的nodejs版本可以选择8或12，如果你使用了nodejs的api，在本地测试之后部署到云端建议测试一下兼容性。如果只使用uniCloud的api，无需顾虑兼容性。
3. 本地环境的云函数没有超时限制
云函数超时时间、运行内存配置，在本地调试时不会生效。
4. return 策略差异
[详见](cf-functions.md?id=return)
5. 公用模块使用注意
- 需要在云函数内执行`npm install ../common/xxx`安装公共模块，详细请参考[云函数公用模块](uniCloud/cf-common.md)
- 如果使用`HBuilderX 3.0.0`及以上版本，可以直接在云函数目录右键选择“管理公共模块依赖”进行公共模块的引入
- 如果使用到加密的公共模块则此云函数不可本地运行
- `HBuilderX 3.0.0`版本运行uniCloud项目时，uniCloud本地调试插件会自动进行云函数依赖安装（包括公共模块和package.json里面的其他依赖）
6. 时区问题
uniCloud云端的云函数使用的时区是utc+0，本地运行时使用的是本机时间，中国一般是+8。在使用“时间戳”时两者没有差异，但如果要获取年、月、日、小时要注意时区的差异。
以下方式可以获取指定时区的年、月、日、小时，可以参考一下
```js
// 获取偏移后的Date对象，例如utc+x时offset就传x
function getOffsetDate (offset) {
return new Date(
Date.now() + (new Date().getTimezoneOffset() + (offset || 0) * 60) * 60000
)
}
// 获取utc+8的小时数
const hour = getOffsetDate(8).getHours()
// 获取时间戳无需使用此方式utc+0时间戳是与utc+8时间戳一致的
```
推荐使用`<uni-dateformat>`组件格式化显示日期，[详情](https://ext.dcloud.net.cn/plugin?id=3279)
7. 调用其他云函数
“本地运行云函数”时云函数内callFunction会调用云端已部署的云函数
“客户端连接本地云函数时”云函数内callFunction会调用本地云函数
8. 数据与存储
请务必注意云函数在本地运行时依然是连接的云端数据库与存储
云函数上传文件到云存储只有腾讯云支持。当然也可以在前端直接上传文件，此时阿里云腾讯云均支持。
9. 插件市场加密插件
插件市场销售的加密云函数或公共模块，在未购买获得源码前，无法在本地运行。本地运行时会自动请求云端已部署的云函数。请留意控制台输出。
发送clientDB请求时，如果使用了加密的action（在插件市场销售），当前请求会使用云端已部署资源而不是本地资源（包括schema、validateFunction、action），请留意控制台输出。
10. 其他注意事项
- 虽然云函数、数据库schema、validatefunction在本地，但云存储、数据库的数据和索引，仍然在云端。也就是开发机不能完全脱线开发。只是代码可以在本地写，免上传就能联调。
- 连接线上环境时请记得上传本地的schema、validatefunction、action
- 切换云端、本地，无需重新运行客户端
- 不同平台可以有不同的配置。但同一平台，如安卓和iOS都是app-plus，则对应着同一个配置，或者两台安卓手机也只能有一个配置
- 客户端在每次发送云函数请求之前，会发送一条请求到本地调试服务，本地服务会根据当前用户选择来通知客户端该访问本地云函数还是云端云函数
- 客户端连接本地云函数时，云函数内的callFunction也会调用本地云函数。除非目标云函数是插件市场售卖的加密云函数，此时不会调用本地，仍会调用云端
- 如果项目内关联了两个服务空间，需要在`.hbuilderx/launch.json`内配置provider参数指定哪个服务空间使用本地调试
- 当前项目运行的所有客户端都停止运行时，对本项目的调试服务会关闭，已经运行到手机的客户端将无法连接本地云函数
- 在h5端network面板的会看到一些`Request Method: OPTION`的请求，这些是跨域预检请求，忽略即可。请参考：[HTTP 的 OPTIONS 方法](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods/OPTIONS)
- 本地不支持使用了腾讯云自定义登录的场景
- 开发小程序时如果想使用本地云函数进行调试，请开启小程序的忽略安全域名校验
- 小程序体验版无法连接本地服务，如果发布成小程序体验版请务必使用发行模式
- 如果在使用HBuilderX过程中切换了电脑网络后本地调试服务无法访问，则需要重启一次HBuilderX
## 运行云函数时配置运行测试参数@runparam
在云函数的上传运行菜单或右键菜单中，有`配置运行测试参数`的功能。
可以打开一个json，配置运行参数。配置该json后，运行云函数时会将该json作为云函数调用的上行参数处理，可以在云函数中接收到参数。
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/37245420-4b1b-11eb-b997-9918a5dda011.jpg"/>
</div>
在云函数目录右键运行云函数，也可以在云函数编辑器里，按`Ctrl+r`运行快捷键，或点工具栏的运行
<div align=center>
<img src="https://img.cdn.aliyun.dcloud.net.cn/uni-app/uniCloud/run-function-with-param-1.jpg"/>
</div>
此时云函数运行会携带所配置的运行参数
<div align=center>
<img style="max-width:750px;" src="https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-dc-site/84352e10-4b1b-11eb-8ff1-d5dcf8779628.jpg"/>
</div>
**模拟客户端类型**
如果需要模拟客户端类型可以在运行参数内添加clientInfo字段
```
{
"otherParam": "***",
"clientInfo":{
OS: "ios" // 系统类型 ios、android
PLATFORM: "h5" // 客户端类型 app-plus、h5、mp-weixin、mp-alipay等
}
}
```
## 断点调试云函数
> HBuilderX 3.2.10起，本地运行云函数及客户端连接本地云函数支持断点调试
开启断点调试方式如下图所示，在uniCloud本地运行环境启动后，在uniCloud控制台右上角选择开启断点调试。
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/015ee94b-23af-4aa0-b39b-b788b010dc4d.jpg"/>
</div>
开启调试后会出现调试界面，如下图所示。和浏览器的调试功能类似，详情可以参考：[JavaScript调试器](https://developer.mozilla.org/zh-CN/docs/Learn/Common_questions/What_are_browser_developer_tools#javascript%E8%B0%83%E8%AF%95%E5%99%A8)
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/ed6120d4-2882-44b5-892f-f3fec8493e8b.jpg"/>
</div>
在调试文件的编辑器界面的行号处双击可以插入断点，也可以右键选择更多操作（添加/删除/禁用断点）
<div align=center>
<img style="max-width:750px;" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/fda77798-3cb8-4aaa-8ac9-ba718520352e.jpg"/>
</div>
如需从调试界面切换回项目视图，可以在项目管理器底部点击按钮进行切换
<div align=center>
<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/9cc24dbe-cde9-4a82-8872-4803ada97298.jpg"/>
</div>
uni-app前端也支持debug调试，注意不要混淆。
在调试面板上方有断点step按钮，鼠标悬浮上去可看到快捷键。可以单步调试。调试面板的使用教程同客户端调试，[详见](/tutorial/debug/h5-debug.md)
## 云端日志@uniCloudlogger
发布后的云函数，在 [uniCloud web控制台](https://unicloud.dcloud.net.cn/) -> 云函数 下也有日志。
除了常规的运行日志、错误日志，也可以通过 API `uniCloud.logger` 打印日志。
使用腾讯云时，以 `uniCloud.logger` 方式打印的日志会保留30天，普通 console 方式打印的日志会保留7天。
使用阿里云时，两种方式都是只能保留7天。
|接口 |描述 |
|:-: |:-: |
|uniCloud.logger.log |以 log 日志等级输出日志 |
|uniCloud.logger.info |以 info 日志等级输出日志 |
|uniCloud.logger.warn |以 warn 日志等级输出日志 |
|uniCloud.logger.error|以 error 日志等级输出日志|
\ No newline at end of file
docs/uniCloud/uni-id-summary.md
浏览文件 @ e05f5578
本文档适用于`uni-id 4.0.0`及以上版本，需 HBuilderX 3.5.0 及以上版本。旧版本文档请访问：[uni-id 3.x.x 文档](uniCloud/uni-id-3.md)
## 概述
## 需求背景
99%的应用，都要开发用户注册、登录、发送短信验证码、修改密码、密码加密保存、密码防探测、token管理、页面访问权限、注册用户统计等众多功能，从前端到后端都需要。
......@@ -12,103 +12,129 @@
[clientDB](uniCloud/clientDB)、[DB Schema](uniCloud/schema)、[uni-starter](https://ext.dcloud.net.cn/plugin?id=5057)、[uni-admin](uniCloud/admin)，这些产品都基于`uni-id`的账户体系。可以说`uni-id`是uniCloud不可或缺的基础能力。
## 组成部分
## uni-id 的价值
1. 节省了大量重复劳动
2. 降低门槛，前端开发者无需研究数据库如何设计、账户安全如何保障
3. 多系统打通用户和上下游协同
1. 云数据库
关于第三点，着重强调下。
十几张用户相关的[opendb数据表](uniCloud/opendb)，如[uni-id-users](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-users/collection.json)、[uni-id-roles](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-roles/collection.json)、[uni-id-permissions](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-permissions/collection.json)。
一个应用，往往需要集成多个功能模块。比如一个电商应用，需要一个基本电商模板，还需要客服聊天模板、统计看板模板。
主表为 `uni-id-users` 表，保存用户的基本信息。扩展字段有很多，如实名认证数据、工作履历数据。由于MongoDB的特性，开发者可以自由扩展字段。
在插件市场，每类模板插件都能找到，但他们如果不是基于同一套用户体系设计，就很难整合。
所有`uni-id`的数据表，不管在HBuilderX中新建DB Schema还是在uniCloud web控制台新建表的界面上，都可以选择模板直接建好。
所有uniCloud的标准应用，都基于`uni-id`来做。`uni-id-common`公共模块自动内置在每个服务空间里的。
2. 云端核心[公共模块](https://uniapp.dcloud.io/uniCloud/cf-common.html) [uni-id-common](uniCloud/uni-id-common.md)
有了统一的账户规范，并且围绕这套账户规范，有各种各样插件，那么开发者可以随意整合这些插件，让数据连同。
uni-id-common公共模块包含了账户体系服务端的核心权限、token管理，内置在每个uniCloud服务空间里。
规范，还可以让上下游充分协同。插件市场会出现各种数据迁移插件，比如把从discuz里把用户迁移到`uni-id`中的插件，相信围绕这套规范的产业链会非常活跃。
uniCloud众多功能（如DB Schema的权限、uni-id-co）都依赖uni-id-common。如果开发者想要在自己的云函数里校验前端用户token，也需要引用uni-id-common公共模块。
目前插件市场上各种优秀的uniCloud轮子，几乎都是基于`uni-id`的。
uni-id-common这个uni_modules包括了4张opendb表，分别为：
- 用户表 uni-id-users
- 权限表 uni-id-permissions
- 角色表 uni-id-roles
- 用户日志表 uni-id-log
## 功能清单
3. 云端一体页面模板 [uni-id-pages](uniCloud/uni-id-pages)
`uni-id`已完成的功能：
基于uni-id-common，DCloud还提供了一组完整的前端页面和后端[云对象](https://uniapp.dcloud.io/uniCloud/cloud-obj.html) ，合称`uni-id-pages`。
- 注册、登录、发送短信验证码、密码加密保存、修改密码、忘记密码、头像管理、token管理、rbac权限角色体系、页面访问权限路由控制、用户邀请裂变、用户签到、日志记录、账户防刷
uni-id-pages的功能包括：用户注册（含用户协议、隐私协议）、退出、修改密码、忘记密码等各种功能，同时适配PC宽屏和各种手机平台（App、H5、小程序）。
关于登录方式，目前已实现
此外，DCloud的其他产品也为uni-id提供了众多支持：
- [uni-admin后台管理框架](https://uniapp.dcloud.io/uniCloud/admin.html)，为uni-id提供了现成的用户、角色、权限的后台管理功能，以及注册用户统计报表。
- uni-app框架内置的uniCloud客户端SDK，自动处理了uni-id的token的网络传输（uni-app 2.7.13+版本）、续期（uni-app 3.4.13 +版本），也就是说开发者无需自己管理token了。
- 账户密码登录
- 手机号+短信验证码登录 （内置uniCloud短信能力）
- App手机号一键认证，免验证码（内置uni-app App一键登录能力）
- 三方登录：App中的微信登录、Apple ID、QQ登录；微信小程序中的微信登录；支付宝小程序中的支付宝账户登录；QQ小程序中的QQ登录
以上全部是开源的。
由于三方登录很多，DCloud没有精力全部实现，在uni-id-co中留下了空实现，欢迎开发者自行补充、提交pr或发布扩展插件，共同完善`uni-id`。。
**历史遗留**
后续计划：DCloud未来将内置 微信扫码登录和公众号登录、邮箱验证集成、facebook等海外主流社交账户登录、活体检测。
在HBuilderX 3.5之前，DCloud提供了一个公共模块[uni-id](https://ext.dcloud.net.cn/plugin?id=2116)（注意不叫uni-id-common）和一个示例性云函数uni-id-cf（集成在uni-starter和uni-admin中）。
其他方面，各种常见开源项目如discuz、wordPress、ecshop的用户导入插件，不属于`uni-id`主工程，欢迎开发者单独提交插件到插件市场。
老的公共模块uni-id是一个大而全的账户管理公共模块，体积太大，不适合被其他云函数引用。比如某个业务云函数需要校验用户token，引用的uni-id公共模块还包含了忘记密码的代码，很浪费资源。
## 组成结构
在云对象发布之前，DCloud基于云函数方式提供了uni-id-cf。但在HBuilderX 3.5 以后，推荐使用基于云对象的[uni-id-pages](uniCloud/uni-id-pages)，代码更简单清晰。
`uni-id`贯穿了uni-app前端到uniCloud后端的各个环节。
从HBuilder 3.5起，[uni-id](https://ext.dcloud.net.cn/plugin?id=2116)和uni-id-cf都将被淘汰，不再更新。老的公共模块uni-id被拆开，变成了[uni-id-common](uniCloud/uni-id-common)公共模块和uni-id-co云对象。
|模块 |说明 |
|-- |-- |
|前端uni-app框架的相关API |uniIdRouter页面路由、token管理客户端API |
|前端页面uni-id-pages |登录、注册、修改密码、忘记密码、个人中心、修改头像等前端页面 |
|网络传输自动管理用户token |自动保存、续期token、网络自动传输token |
|云端云对象uni-id-co |与uni-id-pages搭配的云对象，相关业务的云端部分 |
|云端配置uni-config-center |在uni-config-center下提供各种配置 |
|云端公共模块uni-id-common |用于云函数或云对象集成该模块验证token身份 |
|云数据库的用户相关数据表 |uni-id-users等各种opendb数据表 |
|uni-admin |Admin管理后台，包括用户角色权限管理、注册用户统计 |
uni-id-common很精简，只包括token和权限，适合被所有云函数引用。
uni-id-co则是一个更加比uni-id-cf更完善和规范的用户管理的云对象。
1. 云数据库的uni-id相关表
老版升级指南，[详见](uniCloud/uni-id-pages?id=m-to-co)
数据库是一个系统的核心，uni-id首先规范化了十几张用户相关的[opendb数据表](uniCloud/opendb)，
## uni-id 对开发者的价值
其中最为重要的4张opendb表，如下：
- 用户表 [uni-id-users](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-users/collection.json)
- 权限表 [uni-id-permissions](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-permissions/collection.json)
- 角色表 [uni-id-roles](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-roles/collection.json)
- 用户日志表 [uni-id-log](https://gitee.com/dcloud/opendb/blob/master/collection/uni-id-log/collection.json)
1. 节省了大量重复劳动
2. 降低门槛，前端开发者无需研究数据库如何设计、账户安全如何保障
3. 多系统打通用户和上下游协同
主表为`uni-id-users`表，保存用户的基本信息。扩展字段有很多，如实名认证数据、工作履历数据。由于MongoDB的特性，开发者可以自由扩展字段。
关于第三点，着重强调下。
所有`uni-id`的数据表，不管在HBuilderX中新建 `DB Schema` 还是在 uniCloud web控制台新建表的界面上，都可以选择模板直接建好。
一个应用，往往需要集成多个功能模块。比如一个电商应用，需要一个基本电商模板，还需要客服聊天模板、统计看板模板。
2. 云端公共模块uni-id-common
在插件市场，每类模板插件都能找到，但他们如果不是基于同一套用户体系设计，就很难整合。
uni-id-common公共模块包含了账户体系服务端的核心权限、token管理，内置在每个uniCloud服务空间里。
所有uniCloud的标准应用，都基于`uni-id`来做。`uni-id`公共模块自动内置在每个服务空间里的。
如开发者需要在自己的云函数/云对象里校验前端用户token，则需要引用uni-id-common公共模块。
有了统一的账户规范，并且围绕这套账户规范，有各种各样插件，那么开发者可以随意整合这些插件，让数据连同。
uniCloud众多功能（如`DB Schema`的权限、uni-id-co）也都依赖 uni-id-common。
规范，还可以让上下游充分协同。插件市场会出现各种数据迁移插件，比如把从discuz里把用户迁移到`uni-id`中的插件，相信围绕这套规范的产业链会非常活跃。
[详见](uniCloud/uni-id-common.md)
事实上，[clientDB](uniCloud/clientDB)、[DB Schema](uniCloud/schema)、[uni-starter](https://ext.dcloud.net.cn/plugin?id=5057)、[uniCloud admin](uniCloud/admin)等重要uniCloud产品，以及插件市场上各种优秀的轮子，都是基于`uni-id`的。
3. 云端[uni-config-center](/uniCloud/uni-config-center.md)下的uni-id配置
## 现状和未来
`uni-id`在云端有很多配置，比如密码加密秘钥、短信和微信登录的appsecret等等。在`uni-config-center`下的`uni-id`目录下的config.json里存放着这些配置。
`uni-id`已完成的功能：
[详见](uniCloud/uni-id-summary.md?id=config)
- 注册、登录、发送短信验证码、密码加密保存、修改密码、重置密码、头像管理、token管理、rbac权限角色体系、页面访问权限路由控制、用户邀请裂变、用户签到、日志记录、账户防刷
4. 客户端API
uni-app框架内置了uni-id的token管理。
关于登录方式，目前已实现
uni-app与uniCloud搭配且使用uni-id，登录后自动下发token、网络传输层自动传输token（uni-app 2.7.13+版本）、token临近过期会自动续期（uni-app 3.4.13 +版本），也就是说开发者无需自己管理token了。
- 账户密码登录
- 手机号+短信验证码登录
- App手机号一键认证，免验证码
- 三方登录：App中的微信登录和Apple ID和QQ登录、微信小程序中的微信登录、支付宝小程序中的支付宝账户登录 、QQ小程序中的QQ登录
uni-app客户端还有一批uni-id相关的内置API：
- uniIDHasRole：判断当前用户是否拥有某角色。[详情](/api/global.html#uniidhasrole)
- uniIDHasPermission：判断当前用户是否拥有某权限。[详情](/api/global.html#uniidhaspermission)
- uniCloud.getCurrentUserInfo()：客户端获取当前用户信息。[详情](/uniCloud/client-sdk.html#client-getcurrentuserinfo)
关于还缺少的部分，哪些DCloud在完善，哪些希望开发者给共同完善开源项目，计划与边界公布如下：
5. 云端一体页面模板 [uni-id-pages](uniCloud/uni-id-pages)（含uni-id-co）
1. 无计划做的
基于uni-id-common，DCloud还提供了一组完整的前端页面和后端[云对象](/uniCloud/cloud-obj.html) ，合称`uni-id-pages`。
百度、快手、快应用等小程序的登录，以及微博等App端的登录。
uni-id-pages的功能包括：用户注册（含用户协议、隐私协议）、退出、修改密码、忘记密码等各种功能，同时适配PC宽屏和各种手机平台（App、H5、小程序）。
2. 有计划做但不是近期计划
此外，DCloud的其他产品也为uni-id提供了众多支持：
- [uni-admin后台管理框架](/uniCloud/admin.html)，为uni-id提供了现成的用户、角色、权限的后台管理功能，以及注册用户统计报表。
web的微信扫码登录、字节小程序登录、facebook等海外主流社交账户登录、邮箱验证集成、活体检测。
以上全部是开源的。
**历史遗留**
在HBuilderX 3.5之前，DCloud提供了一个公共模块[uni-id](https://ext.dcloud.net.cn/plugin?id=2116)（注意不叫uni-id-common）和一个示例性云函数uni-id-cf（集成在uni-starter和uni-admin中）。
老的公共模块uni-id是一个大而全的账户管理公共模块，体积太大，不适合被其他云函数引用。比如某个业务云函数需要校验用户token，引用的uni-id公共模块还包含了忘记密码的代码，很浪费资源。
在云对象发布之前，DCloud基于云函数方式提供了uni-id-cf。但在HBuilderX 3.5 以后，推荐使用基于云对象的[uni-id-pages](uniCloud/uni-id-pages)，代码更简单清晰。
从HBuilder 3.5起，[uni-id](https://ext.dcloud.net.cn/plugin?id=2116)和uni-id-cf都将被淘汰，不再更新。老的公共模块uni-id被拆开，变成了[uni-id-common](uniCloud/uni-id-common)公共模块和uni-id-co云对象。
uni-id-common很精简，只包括token和权限，适合被所有云函数引用。
uni-id-co则是一个更加比uni-id-cf更完善和规范的用户管理的云对象。
老版升级指南，[详见](uniCloud/uni-id-pages?id=m-to-co)
上述功能均欢迎其他开发者在开源项目上提交pr，或在插件市场发布插件，共同完善`uni-id`。
其他方面，各种常见开源项目如discuz、wordPress、ecshop的用户导入插件，不属于`uni-id`主工程，欢迎开发者单独提交插件到插件市场。
## 快速上手@start
......@@ -841,11 +867,13 @@ module.exports = {
**注意**
- pages.json内有`uniIdRouter`节点上述逻辑才会生效，自HBuilderX 3.5.0起创建空项目模板会自动配置空的`uniIdRouter`节点
- uniIdRouter底层使用navigateTo、redirectTo、reLaunch、switchTab的拦截器进行页面跳转拦截，不会拦截进入首页和点击原生tabbar。一般tabbar页面都不做自动跳转，而是在页面内再提供登录按钮。比如tabbar上有购物车或个人中心，点击购物车后在购物车页面内部会放一个提示语和按钮，告知用户需要登录。在页面内判断用户是否登录，使用API[uniCloud.getCurrentUserInfo()](https://uniapp.dcloud.io/uniCloud/client-sdk.html#client-getcurrentuserinfo)
- uniIdRouter底层使用navigateTo、redirectTo、reLaunch、switchTab的拦截器进行页面跳转拦截，不会拦截进入首页和点击原生tabbar。
一般tabbar页面都不做自动跳转，而是在页面内再提供登录按钮。比如tabbar上有购物车或个人中心，点击购物车后在购物车页面内部会放一个提示语和按钮，告知用户需要登录。
在页面内判断用户是否登录，使用API[uniCloud.getCurrentUserInfo()](https://uniapp.dcloud.io/uniCloud/client-sdk.html#client-getcurrentuserinfo)
## 错误码@errcode
## 云端错误码@errcode
|错误码 |错误信息 |说明 |
|错误码errCode |错误信息errMsg |说明 |
|---- |---- |---- |
|0（数字） |成功 |- |
|uni-id-token-expired |登陆状态失效，token已过期 |- |
......@@ -1034,16 +1062,7 @@ uni-id-users表内存储的password字段为使用hmac-sha1生成的hash值，
**注意**
- 由于角色权限缓存在token内，可能会存在权限已经更新但是用户token未过期之前依然是旧版角色权限的情况。可以调短一些token过期时间来减少这种情况的影响。或者使用redis来缓存用户权限
- admin角色token内不包含permission，如需自行判断用户是否有某个权限，要注意admin角色需要额外判断一下，写法如下
```js
const {
role,
permission
} = await uniID.checkToken(event.uniIdToken)
if(role.includes('admin') || permission.includes('your permission id')) {
// 当前角色拥有'your permission id'对应的权限
}
```
- admin角色token内不包含permission，如需自行判断用户是否有某个权限，要注意admin角色需要额外判断一下，只要角色为admin或permission包含期待值，都视为拥有权限
### 自定义token内容@custom-token
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或