uni-app操作uniCloud数据库必须正确配置环境、权限和调用时机；检查uniCloud文件夹、manifest.json配置、H5的useUniCloud开关；where/doc/get顺序严格绑定；schema权限修改后需上传；$lookup仅限云函数且字段类型须一致。
uni-app 操作 uniCloud 数据库必须走 uniCloud.database()，但直接写这行代码不报错 ≠ 能跑通——90% 的问题出在环境没配好、权限没开、或调用时机不对。
uniCloud.database() 报 undefined 或 not a function 怎么办
这不是语法错误，是项目根本没接入云开发环境。
- 检查项目根目录下是否有
uniCloud文件夹；没有？说明没关联云空间 → 打开 HBuilderX，右键项目 →「uniCloud」→「关联云空间」，选一个已创建的（DCloud 控制台里手动开通的） -
manifest.json里必须有正确配置："uni-app": { "cloud": { "service-space-id": "your-space-id" } }，且服务商（aliyun或qcloud）要匹配 - H5 端额外加一行：
"h5": { "useUniCloud": true }，否则前端直连被禁用，请求发不出去 - 小程序/App 端无需额外配置，但首次调用建议放在
onReady或用户触发后，别在data初始化里就执行
where / doc / get 顺序写错导致查不到数据
这三个方法不是随便链的，顺序和返回值类型严格绑定。
-
db.collection('users').where({ status: 'active' }).get()✅ 查符合条件的所有文档 -
db.collection('users').doc('xxx_id').get()✅ 查单条，最快最安全；doc()返回的是文档引用，不支持再接where() -
db.collection('users').where({ _id: 'xxx_id' }).get()⚠️ 能查但低效，结果是数组，得取res.result.data[0] -
db.collection('users').doc('xxx_id').where(...)❌ 报错：文档引用对象没有where方法 - 字段名大小写敏感，
where({ UserId: 123 })查不到user_id字段；未建索引的字段（如text类型）做模糊查询可能超时
add / update / remove 提示 permission denied
不是代码写错了，是数据库权限没生效。
- 打开
uniCloud-aliyun/database/users.schema.json（集合名换成你自己的），确认"permission"下对应操作为true，例如："update": true - 改完必须右键该文件 →「上传 DB Schema」；只保存文件不上传，权限不会同步到云端
- 前端直连受此权限控制；云函数里操作数据库则走服务端身份，不受这个限制——这是绕过权限卡点的常用方式
- 如果用
db.command.set或db.command.remove等原子操作，也要确保对应字段在 schema 中允许写入
联表查询 $lookup 返回空数组或结构不对
uniCloud 不支持 SQL JOIN，$lookup 是模拟联表，但行为和预期常有偏差。
-
$lookup必须写在where()后、get()前，且只能在云函数里用（前端 JQL 不支持） -
localField和foreignField类型必须一致：比如articles.user_id是字符串，user._id就不能是 ObjectId；否则匹配失败，返回空数组 -
as: 'author'的结果永远是数组，哪怕只匹配一条，前端取值得写item.author[0]?.nickname，不是item.author.nickname - 跨集合查询不能跨服务空间，
from只能填当前数据库里的集合名，大小写敏感 - H5 调试时记得 manifest.json 开
"h5": { "useUniCloud": true }，并勾选「H5 使用本地云函数」，否则看不到真实报错
真正容易被忽略的点是：schema 权限改了不上传、字段类型不一致、H5 没开本地调试开关——这些地方一漏，代码逻辑完全正确也会查不到数据或报错。别急着改代码，先盯住这三处。
