uniCloud是uni-app官方内置云开发能力，需先在DCloud后台创建云空间并用HBuilderX关联，否则callFunction报undefined、无uniCloud菜单等；调用须在onReady或用户触发后，且函数需已部署；数据库查询必须加.get()才执行。
uni-cloud 不是插件，也不是可选模块——它是 uni-app 官方内置的云开发能力，直接集成在项目中，无需额外 npm install，但必须通过 HBuilderX 创建并启用。
如果你刚建好 uni-app 项目却找不到 uniCloud 目录、调用 uniCloud.callFunction 报错为 undefined，或部署后函数在微信小程序里始终返回 “云函数未找到”，说明你跳过了最关键的一步：初始化云空间并关联到项目。这不是代码问题，而是环境配置缺失。
uniCloud.init 前必须完成云空间创建
uniCloud.init 只负责连接，不负责创建资源。它需要一个真实存在的云空间 ID（spaceId）和区域（如 aliyun 或 qcloud），而这个空间必须提前在 DCloud 后台手动开通：
- 打开 https://www.php.cn/link/dff6cca765611a8cb9b63986b83c636c 登录你的 DCloud 账号
- 进入「云空间管理」→「新建云空间」
- 选择服务商（阿里云/腾讯云）、地域、空间名称（如
myapp-prod） - 等待状态变为「已就绪」（通常 1–2 分钟）
完成之后，才能在 HBuilderX 中右键项目 → 「uniCloud」→ 「关联云空间」，选中刚创建的空间。此时项目根目录下才会生成 uniCloud 文件夹，并自动写入 service、database 等子目录。
常见错误现象：
-
uniCloud.callFunction报错TypeError: Cannot read property 'callFunction' of undefined - HBuilderX 右键无「uniCloud」菜单项
-
manifest.json中没有"uniCloud"字段
原因几乎全是：没登录 DCloud 账号，或账号没开通云空间，或 HBuilderX 没同步登录态（重启 HBuilderX 并重新登录可解决）。
uniCloud.callFunction 的调用时机很关键
不能在 onLoad 里直接调用，尤其不能在 App.vue 的 onLaunch 里裸调——因为此时客户端可能尚未完成云环境初始化，或用户未登录导致权限拒绝。
推荐做法：
- 在页面
onReady或用户触发动作（如按钮点击）后调用 - 显式加上
uniCloud.init的容错判断（虽然关联后一般自动生效，但真机调试时偶发延迟） - 使用
try/catch包裹，捕获uniCloud.callFunction的失败（比如网络超时、云函数不存在、权限不足）
示例：
async onLoad() {
try {
const res = await uniCloud.callFunction({
name: 'get-user-info',
data: { userId: 'abc123' }
})
console.log(res.result)
} catch (err) {
console.error('云函数调用失败:', err.message)
// err.code === 'FUNCTION_NOT_FOUND' 表示函数名拼错或未部署
}
}注意：
-
name必须与云函数文件夹名完全一致（区分大小写） - 函数必须已右键「上传部署」，且状态为「已部署」（HBuilderX 底部状态栏有提示）
- 微信小程序端需确保
manifest.json中已填写正确的appid，否则云函数权限校验会失败
uniCloud.database 查询必须加 .get() 才真正执行
很多人写：
const db = uniCloud.database()
const collection = db.collection('user')
collection.where({ status: 'active' }) // ❌ 这只是构造查询，没发请求这不会报错，也不会返回数据，只是返回一个查询对象。必须显式调用 .get()（查列表）或 .getOne()（查单条）：
const res = await db.collection('user')
.where({ status: 'active' })
.get() // ✅ 此刻才发起网络请求容易忽略的点：
-
.get()返回的是{ result: [...] }，不是直接数组，要取res.result - 小程序端默认开启安全规则，未登录用户无法读写数据库；若测试阶段想绕过，需在云数据库控制台临时关闭「强制登录」或添加白名单规则
-
where中不能使用 JavaScript 原生方法（如new Date()），应改用db.serverDate()
云开发真正的门槛不在语法，而在环境链路是否完整：DCloud 账号 → 云空间创建 → HBuilderX 关联 → 函数部署 → 小程序 AppID 绑定 → 客户端显式调用。任一环断开，都会表现为“函数没反应”或“数据库查不到”，而不是清晰的错误提示。调试时优先检查 HBuilderX 底部状态栏的云空间图标是否为绿色“已连接”，再看云函数列表里部署状态是否为“已部署”。
