云对象编写需严格遵循结构、导出、部署与调用规范：必须含index.obj.js和type为"cloudobject"的package.json；module.exports须为同步函数对象；须右键上传部署；前端应在onReady或用户交互中调用importObject并await，且仅阿里云空间支持。
uni-app 编写云对象不是写个 JS 文件就完事，关键在结构、导出方式、部署时机和调用上下文——漏掉任一环，uniCloud.importObject() 会返回 undefined，或者方法调用直接静默失败。
云对象文件结构必须含 index.obj.js 和 package.json
右键 uniCloud-aliyun/cloudfunctions →「新建云对象」后，HBuilderX 自动生成两个文件：index.obj.js（主逻辑）和 package.json（声明类型为 "type": "cloudobject"）。
如果手动创建或重命名过文件，务必检查：
-
package.json中"type"字段值必须是字符串"cloudobject"，不能是"cloudfunction"或缺失 -
index.obj.js必须是顶层入口，不支持子目录嵌套或改名（如main.js） - 云对象名称（即文件夹名）只能含小写字母、数字、下划线，且不能以数字开头；例如
todo合法，TodoService或123api会部署失败
module.exports 导出必须是纯函数对象，不能包在 async/await 里
云对象方法在服务端运行时由 uniCloud 运行时自动包装为异步，你写的函数本身应是同步签名。写成 async add() { ... } 看似合理，但会导致 this.getHttpInfo() 等上下文方法不可用，且参数透传异常。
正确写法示例（带基础校验和上下文访问）：
module.exports = {
add(title, content) {
title = (title || '').trim()
content = (content || '').trim()
if (!title || !content) {
return { errCode: 'INVALID_INPUT', errMsg: '标题和内容均不能为空' }
}
// this 可用，比如获取请求方式
const method = this.getHttpInfo?.().httpMethod || 'UNKNOWN'
console.log('method:', method)
return { errCode: 0, errMsg: '添加成功', data: { title, content } }
},
_before() {
// 所有方法执行前触发，适合统一鉴权、日志打点
console.log('request start at', Date.now())
},
_after(error, result) {
// 所有方法执行后触发，error 为抛出异常，result 为返回值
if (error) console.error('cloud object error:', error)
}
}
-
_before和_after是生命周期钩子，非必需，但比在每个方法里重复写更安全 - 不要在方法里直接
throw new Error()，uniCloud 期望返回标准格式对象（{ errCode, errMsg, data? }），否则前端catch到的e.errMsg可能为空 - 参数是扁平传入的，不是
event对象；若需 header、query、body 全量信息，请用this.getHttpInfo()
必须先「部署」再调用，且前端调用需满足生命周期约束
云对象代码保存后不会自动上线，必须右键云对象文件夹 →「上传并部署」，HBuilderX 底部状态栏显示「部署成功」才算生效。常见误操作：
- 前端在
onLoad里就调用uniCloud.importObject('todo')—— 此时uniCloud可能还未初始化完成，返回undefined - 在组件
data里提前 import —— 实际 import 是异步加载行为，不能当同步变量用 - 用 H5 模式调试时没开「启用 uniCloud」开关（manifest.json → 「SDK 配置」→ 勾选 uniCloud）
安全写法是：在用户可交互事件中（如按钮点击），或 onReady 后再 import 并 await 调用：
methods: {
async handleAdd() {
try {
const todo = uniCloud.importObject('todo')
const res = await todo.add('学习云对象', '从 index.obj.js 开始')
uni.showToast({ title: res.errMsg })
} catch (e) {
uni.showModal({ title: '错误', content: e.errMsg || '未知错误' })
}
}
}
阿里云空间关联和跨端兼容性容易被忽略
云对象只在阿里云版 uniCloud 支持（腾讯云版目前仅支持云函数），且必须完成三步绑定：
- HBuilderX 项目已勾选「启用 uniCloud」并选择「阿里云」
- 已在 DCloud 控制台创建阿里云服务空间，并在 HBuilderX 中「关联云服务空间」成功（右键
uniCloud-aliyun→「关联云服务空间」） - 前端调用时未混用
uniCloud.callFunction()（那是云函数的 API，对云对象无效）
另外，云对象在 App、小程序、H5 均可用，但 H5 端需确保域名已配置白名单（控制台 → 云服务空间 →「安全配置」→「HTTP 访问白名单」），否则请求会被拦截且控制台无明显报错。
