一、文件结构与核心文件作用
1. 目录位置
项目uniCloud/支付宝云-xxx/database/下两类核心文件：
xxx.schema.json：数据表结构定义文件（集合 Schema）- 定义数据表字段、类型、必填、默认值、权限、数据校验规则
- 必须右键上传部署到云空间，云端数据库才会生效表约束
*.jql：JQL 本地查询调试脚本文件（截图里JQL查询.jql） 专门用来本地调试数据库增删改查语句，快捷键F5执行
2. jql 脚本文件内置注释说明（视频原文）
- 用途：本地调试 JQL 操作关联服务空间数据库，等价于客户端
clientDBAPI - 支持普通 JS 语法 + JQL 语句，可写多条代码，仅最后一条 JQL 语句生效
- 执行权限特点：本地运行不受 Schema 权限
permission控制；项目上线后前端受 Schema 权限限制，上线前必须配置好权限规则 - 数据返回限制：查询有最大返回条数上限，官方文档可查
.limit()分页限制 - 官方语法参考地址：uniapp.dcloud.net.cn/uniCloud/jql.html
二、基础 JQL 语法示例（截图演示新增数据）
运行
// 向 demo-user 集合新增一条数据 db.collection('demo-user').add({ // 写入字段数据 })db.collection('表名')：指定操作的数据集合（数据表）.add()：新增单条记录；配套还有.get()查询、.update()更新、.remove()删除
三、Schema（集合结构文件）操作流程
- 新建 / 编辑
demo-user.schema.json定义表结构 - 右键文件 → 上传数据集合 Schema
- 控制台日志提示「上传数据集合 Schema 成功」代表云端表结构更新完成
- 关键：不上传 Schema 到云端，数据库不会启用字段校验、权限控制
上传到云端
四、高频报错：schema is not defined 解决方案（
报错原因
- 未创建对应名称的
xxx.schema.json文件，云端无该集合的结构定义 2 创建了 schema 文件，但没有右键上传部署到云服务空间3 JQL 脚本里写的集合名，和 schema 文件名不匹配（大小写、名称不一致） 4 项目 uniCloud 文件夹未正常关联支付宝云服务空间
修复步骤
1 核对 JQL 中collection('demo-user')的集合名，和 schema 文件名demo-user.schema.json完全一致 2 右键 schema 文件，执行「上传数据集合 Schema」，等待控制台提示上传成功 3 确认 uniCloud 已正常关联支付宝云服务空间，无断连 4 重新按 F5 运行 jql 脚本，报错消失
五、JQL 调试面板功能（界面底部按钮）
- 只看 data：仅展示数据库返回的数据主体，隐藏日志、请求信息
- 本地 schema：调试时读取本地未上传的 schema 文件做校验（仅本地生效）
- 使用云 schema：调试时读取云端已上传的正式 schema 规则（和线上环境一致，推荐调试上线前开启）
六、开发避坑要点
- 本地
.jql调试不受权限限制，不代表前端页面可以随意读写数据库；上线后前端clientDB严格遵循 schema 里permission读写权限配置，必须提前配置 - 大批量查询必须搭配
.limit()分页，否则会触发条数限制，拿不全数据 3 修改 schema 后必须重新上传，云端数据库才会同步字段校验、权限规则，否则修改不生效 4 schema 文件名必须和集合名完全匹配，否则云端识别不到表结构，直接抛出schema is not defined
七、配套开发流程串联
1 HBuilderX 关联支付宝云服务空间 → 2 在 database 目录新建 xxx.schema.json 定义数据表 → 3 上传 Schema 到云端 → 4 创建.jql调试脚本写增删改查 → 5 F5 运行调试语句测试数据库逻辑 → 6 把调试通过的 JQL 移植到页面clientDB业务代码，补充 Schema 权限配置再上线
执行JQL:
在JQL查询.jql文件中输入要执行的jql语句，按F5执行，控制台会打印执行结果。
执行成功后，在uniCloud控制台就会看到该条数据：
