cli创建的项目，如何使用 uniCloud

欢迎到专业群（ uniCloud 官方技术交流群 ） 咨询，群中有相关专业的管理员和群友。

cli创建的项目使用uniCloud，核心思路是：cli项目本身可以正常创建和编译，但uniCloud的云函数运行、发行、关联服务空间等操作必须通过HBuilderX完成。这是因为uniCloud对安全性要求极高，仅支持使用HBuilderX作为开发工具。

具体操作步骤如下：

第一步：将cli项目导入HBuilderX

打开HBuilderX，通过菜单 文件 > 导入 > 从本地目录导入，将cli项目导入。

第二步：检查并获取appid

如果没有appid，需要打开 src/manifest.json，在 基础配置 --> uni-app应用标识 处点击 重新获取。appid是uniCloud识别项目身份的关键标识，不可跳过。

第三步：创建uniCloud云开发环境

在项目根目录（src同级目录）点右键，选择 创建uniCloud云开发环境，选择具体云厂商（支付宝云、阿里云、腾讯云）后创建。这会在项目根目录下生成 uniCloud-aliyun、uniCloud-tcb 或 uniCloud-alipay 等目录。

第四步：关联服务空间

对uniCloud目录点右键，选择 关联服务空间或项目...，选择之前创建的服务空间。如没有服务空间，需要先在 uniCloud控制台 创建。

第五步：初始化数据库和上传云函数

在uniCloud目录右键，选择 初始化向导，按照操作提示上传云函数和数据库schema。

第六步：运行项目

在HBuilderX中打开cli项目，点击 运行 菜单，选择要运行的平台（如浏览器、手机或模拟器、小程序模拟器）运行即可。运行后即可在前端调用云函数和操作数据库。

关键注意事项

1. 运行与发行云函数只能使用HBuilderX的菜单，不可使用package.json内的命令。如果使用 npm run dev:h5 等命令行方式运行，会提示"应用未关联服务空间"，因为命令行方式无法识别HBuilderX中关联的默认服务空间。

2. 虽然uni-app支持vscode等其他ide开发，但因为uniCloud对安全性要求极高，仅支持使用HBuilderX开发。HBuilderX也支持cli，详见 HBuilderX cli文档。

3. 如果HBuilderX菜单运行不能满足需求（例如需要在CI/CD流水线中集成），可以考虑自行初始化服务空间，参考 服务空间初始化文档。

4. 本地运行与云端运行切换：HBuilderX自带云函数本地运行环境，运行项目时默认选择"连接本地云函数"。可以在底部控制台中的前端控制台右上角进行切换为"连接云端云函数"，此时客户端连接的就是真正的现网uniCloud服务器。

5. 云函数上传部署：需要对云函数/云对象点右键上传到uniCloud服务空间，上传后才能在云端生效。本地运行时无需上传，但云端运行前必须上传。

常见问题排查

• 如果运行后提示"应用未关联服务空间"，请确认是否使用了HBuilderX的运行菜单，而不是package.json内的命令。
• 如果提示"cli项目内使用uniCloud需要使用HBuilderX的运行菜单运行项目，且需要在uniCloud目录关联服务空间"，请检查是否已在uniCloud目录右键关联了服务空间。
• 如果云函数调用报错，请检查云函数是否已上传部署、服务空间是否正确、环境变量是否已配置。

详细文档参考：cli项目中使用uniCloud