uni-app本地调试uniCloud无需启动本地服务，本质是连接远程云空间后实时上传调试云函数和数据库；关键在于新建项目时勾选“启用uniCloud”、选择服务商、完成实名认证、正确部署云函数及手动调用db_init初始化数据库。
uni-app 本地调试 uniCloud 不需要启动独立的本地服务进程，所谓“本地调试”实际是指在 HBuilderX 中连接远程云服务空间后，对云函数、数据库等做实时上传 + 调试调用。真正在本地跑通整个 uniCloud 流程的关键，是确保开发环境与云服务空间正确关联、权限可通、部署路径无误。
创建项目时必须勾选「启用 uniCloud」
新建 uni-app 项目时，HBuilderX 的向导界面里有一个关键选项：启用 uniCloud。如果不勾选，后续手动添加会缺失 uniCloud 目录结构和初始化配置，导致右键菜单中没有「创建云函数」「上传云函数」等操作项。即使后期手动建目录，也无法被 IDE 识别为合法云开发项目。
- 必须在新建项目阶段就选择服务商（阿里云 / 腾讯云 / 支付宝云），不能留空或后期切换
- vue3 版本推荐但非强制；若选 vue2，注意部分新 API（如
useUniCloudDB）不可用 - 项目根目录下应自动生成
uniCloud文件夹，内部含cloudfunctions和database子目录
云服务空间未实名认证会导致初始化失败
点击项目右键 →「uniCloud 初始化向导」后，若卡在「选择服务空间」步骤且列表为空，大概率是未完成实名认证。uniCloud 所有厂商（包括支付宝云）均强制要求实名，且认证状态需同步到对应云厂商控制台（如阿里云实名信息需在阿里云账号中心可见）。
- 阿里云/腾讯云用户：登录对应云平台，检查账号是否已完成企业/个人实名
- 支付宝云用户：需用支付宝账号登录 cloud.alipay.com，完成实名并绑定手机号
- 认证通过后，返回 HBuilderX 刷新服务空间列表，通常需等待 30–60 秒才可见新建项
云函数上传失败常见于 node_modules 未清理或路径错误
右键 cloudfunctions 下某个函数文件夹 →「上传部署」报错，典型提示是 upload failed: ENOENT 或 Cannot find module，多数因函数目录内存在冗余 node_modules 或引用了未声明的依赖。
- 云函数运行环境默认不带
npm install步骤，所有依赖必须提前打包进函数目录（npm install --production后保留node_modules） - 禁止在函数目录外安装依赖（如在项目根目录装
generatePPT，再试图让子目录引用） - 上传前确认函数入口文件是
index.js或main.js，且package.json中main字段指向正确 - 若使用 TypeScript，必须先编译为 JS，uniCloud 不直接运行
.ts文件
数据库 schema 初始化必须手动触发 db_init
完成云函数上传后，数据库不会自动建表。schema 定义写在 uniCloud/database/xxx.schema.json，但只有执行 db_init 云函数，才会真正创建集合、应用索引、设置权限。
-
db_init是一个预置云函数，位于cloudfunctions/db_init，首次部署后需右键 →「调用云函数」手动执行一次 - 调用时传空参数
{}即可，成功返回{"code":0,"msg":"init success"} - 若返回
"code":1，检查当前服务空间是否已开通数据库服务（部分免费额度需手动开启） - 修改 schema 后，需重新上传该文件，并再次调用
db_init（它会覆盖式更新）
真正的难点不在部署动作本身，而在于各环节状态不同步：HBuilderX 缓存的服务空间列表、云厂商控制台的实际开通进度、本地 uniCloud 目录的完整性，三者必须严格一致。任意一环滞后，都会表现为“看起来配置好了，但调用就报错”。建议每次卡顿时，先去云厂商控制台确认服务空间状态，再刷新 HBuilderX，最后检查本地目录结构是否被误删或重命名。
