让 Electron、Windows 桌面应用也能直接调用 uniCloud：unicloud-sdk 开源发布

一、为什么要开发这个 SDK？

一直以来，uniCloud 为 uni-app 开发者提供了非常方便的云开发能力。

通过 uniCloud.importObject()，我们可以直接调用云对象，通过 uniCloud.callFunction() 调用云函数，还可以使用云存储、用户登录等能力。

但是，在实际开发中，我遇到了一个问题：

如果我们开发的不是 uni-app，而是 Electron、Windows 桌面应用、普通 Vue/React 网页，甚至 Node.js 工具，还能不能像 uni-app 一样直接调用 uniCloud？

例如：

• 使用 Electron 开发 Windows 桌面软件；
• 使用 Vue、React 开发独立 Web 应用；
• 使用 Node.js 开发本地工具；
• 开发不依赖 HBuilderX 编译的 JavaScript / TypeScript 项目。

这些项目并不能直接使用 HBuilderX 编译时注入的官方 uniCloud 客户端 SDK。

通常的解决方式是将云函数 URL 化，然后通过 HTTP 请求访问。

但这种方式需要额外处理接口路由、请求参数、身份认证和数据交互，也无法直接复用原有的云对象调用方式。

因此，我尝试开发了一个独立的 uniCloud 客户端 SDK，希望让非 uni-app 项目也能够直接使用 uniCloud 的云开发能力。

经过一段时间的研究、协议分析、编码和真实环境测试，目前已经将项目开源并发布到 npm。

项目名称：@yungot/unicloud-sdk

二、项目介绍

unicloud-sdk 是一个独立实现的 uniCloud 客户端 SDK，主要面向 Electron 桌面应用、Windows 软件、Web 应用和 Node.js 项目。

它的目标很简单：

让普通 JavaScript / TypeScript 项目，也能够像 uni-app 一样调用 uniCloud。

主要能力包括：

• 云对象调用：importObject()
• 云函数调用：callFunction()
• 云存储：文件上传、临时链接获取
• uni-id 登录态兼容与 Token 管理
• 客户端身份信息上报
• 设备身份登记与请求签名
• 请求防重放机制
• Electron 主进程与渲染进程安全隔离
• 请求超时、幂等重试和错误处理

技术特点：

• TypeScript 编写，提供完整类型定义
• 零运行时 npm 依赖
• 不需要 HBuilderX 编译
• 支持 Node.js 20+
• 基于 uniCloud 客户端网关协议
• 支持通过宿主桥隔离客户端敏感凭据

它不是简单地封装 HTTP 请求，而是重新实现了 uniCloud 客户端调用协议。

三、与传统 URL 化调用有什么区别？

传统方式通常需要将云函数暴露为 HTTP 接口，然后客户端通过 URL 请求：

const response = await fetch(  
  'https://your-domain.com/api/search',  
  {  
    method: 'POST',  
    headers: {  
      'Content-Type': 'application/json'  
    },  
    body: JSON.stringify({  
      keyword: 'hello'  
    })  
  }  
)  

const result = await response.json()

而使用 unicloud-sdk，可以直接调用云对象：

import { createClient } from '@yungot/unicloud-sdk'  

const cloud = createClient({  
  // 服务空间配置  
})  

const music = cloud.importObject('music')  

const result = await music.search('hello')

调用方式与 uni-app 中的云对象调用方式保持一致。

底层使用 uniCloud 客户端网关协议，而不是云函数 URL 化接口。

需要说明的是，底层网络传输仍然使用 HTTPS POST，区别在于调用入口、协议报文和客户端身份模型，而不是完全不使用 HTTP。

四、Electron 桌面应用的安全设计

这是本项目重点研究和实现的部分。

Electron 应用通常分为主进程和渲染进程。

渲染进程负责界面展示，本质上是一个网页环境。如果直接将服务空间凭据、登录 Token 和设备私钥放在前端代码中，就存在被调试、读取或恶意脚本获取的风险。

因此，SDK 提供了宿主桥机制。

整体设计：

1. 主进程负责创建 uniCloud 客户端，保存服务空间凭据。
2. 设备私钥由主进程管理，并通过系统安全存储机制保护。
3. 渲染进程不能直接获取这些敏感信息。
4. 渲染进程只能通过 preload 暴露的受控接口发起调用。
5. 主进程通过白名单限制允许调用的云对象和方法。
6. 设备请求附带独立的设备身份签名，由云端进行验证。

设备身份机制包括：

• 每台设备独立的 P-256 私钥；
• 设备首次使用时自动登记；
• 请求携带设备证明；
• 请求绑定云对象、方法、参数、登录态和一次性随机数；
• 写操作进行防重放校验；
• 支持设备吊销。

在 Windows Electron 环境下，可以通过 Electron safeStorage 使用系统保护机制保存设备密钥和登录态。

需要强调：设备身份可以证明请求来自已登记设备，但不能单独证明程序一定是正版软件。实际安全还需要结合云端权限校验、账号体系和风控机制。

五、目前已经实现和验证了什么？

项目不是停留在接口设计或简单的 Demo 阶段，目前已经完成多个阶段的实现与验证。

1. 客户端协议实现

• 实现支付宝云客户端网关协议；
• 与官方客户端运行时进行离线黄金报文对照；
• 请求签名、请求头及请求体完成逐字节对照；
• 实现云对象、云函数调用。

2. 真实服务空间验证

在真实 uniCloud 服务空间完成了以下测试：

• Windows 客户端直接调用云对象；
• 云端正常识别客户端来源 source=client；
• 扩展存储上传、下载和删除；
• 设备自动登记；
• 设备请求签名；
• 重放请求拦截；
• 错误码正常回传。

相关阶段测试均已通过。

3. 自动化测试

目前项目包含 62 项单元测试，覆盖：

• 客户端调用；
• 云存储；
• 请求签名；
• 错误处理；
• Token 续期逻辑；
• 宿主桥；
• 设备身份；
• 请求防重放等。

4. 实际项目接入

SDK 已经在一个真实的 Windows Electron 桌面应用中完成接入验证。

这个项目就是我正在开发的桌面音乐播放器：迷笛音乐（MIDI Music）。

在实际项目中，已经使用 SDK 完成：

• Electron 主进程与渲染进程通信；
• 云对象白名单调用；
• 设备身份管理；
• safeStorage 保存设备私钥和登录态；
• 登录 Token 自动携带；
• 云端业务对象统一安全校验；
• Windows 安装版运行验证。

实际项目接入过程中，没有为了适配音乐播放器而修改 SDK 源码。

这也是我决定将 SDK 独立开源的原因：希望把已经验证过的通用能力整理出来，让其他开发者也能使用。

六、如何安装和使用？

项目已经发布到 npm，可以直接安装：

npm install @yungot/unicloud-sdk

引入：

import { createClient } from '@yungot/unicloud-sdk'

创建客户端：

const cloud = createClient({  
  space: {  
    provider: 'alipay',  
    spaceId: 'env-xxxxxxxx',  
    spaceAppId: process.env.UNICLOUD_SPACE_APP_ID,  
    accessKey: process.env.UNICLOUD_ACCESS_KEY,  
    secretKey: process.env.UNICLOUD_SECRET_KEY  
  },  
  appId: '__UNI__YOUR_APP',  
  osName: 'windows'  
})

调用云对象：

const user = cloud.importObject('user')  

const result = await user.getUserInfo()

以上是基本调用示例。Electron 桌面应用建议使用主进程宿主桥模式，不要将长期凭据直接放进渲染进程。

完整配置、Electron 示例、设备身份和云端校验模板，请查看 GitHub 项目文档。

七、目前的支持范围与限制

为了避免开发者误解，这里也说明一下当前项目的能力边界。

已重点验证：

• Windows Electron 桌面应用；
• Node.js 环境；
• 支付宝云服务空间；
• 云对象与云函数调用；
• 扩展存储；
• 设备身份与请求签名。

尚未完成真实环境验证：

• macOS、Linux 实机；
• Web 浏览器实际部署；
• uni-id 完整登录、续期及账号绑定流程；
• 内置存储的完整真实上传流程；
• 设备吊销完整业务流程。

阿里云适配器目前属于实验实现，尚未完成真实联调。

另外，本 SDK 不支持 DCloud 官方 SecureNetwork 双向加密，也不模拟 secretType=both。官方 SecureNetwork 与本项目独立实现的设备身份机制是两套不同的安全体系。

对于原生 uni-app App 和微信小程序，仍然建议使用 DCloud 官方 SDK 及其支持的安全网络能力。

本项目主要解决的是非 uni-app 客户端接入 uniCloud 的问题。

八、开源地址

项目采用 MIT 开源许可证，欢迎开发者使用、研究、反馈问题和参与改进。

npm：

https://www.npmjs.com/package/@yungot/unicloud-sdk

GitHub：

https://github.com/yungot/unicloud-sdk

安装命令：

npm install @yungot/unicloud-sdk

欢迎提交 Issue，反馈使用过程中遇到的问题，也欢迎有兴趣的开发者一起交流 uniCloud 在桌面应用中的使用方式。

九、写在最后

这个 SDK 最初来自一个实际开发需求。

在开发 Windows 桌面音乐播放器时，我希望继续使用自己熟悉的 uniCloud 云开发体系，而不是为了桌面端重新搭建一套后端服务。

于是从研究官方客户端协议开始，逐步完成客户端实现、设备身份机制、请求签名、云端校验和真实项目接入。

整个过程也让我发现，uniCloud 的使用场景并不一定局限于 uni-app。对于已经熟悉 uniCloud 的开发者来说，如果能够在 Electron、Node.js 等环境中复用这套开发模式，就可以减少很多重复的后端开发工作。

所以，我把这部分能力独立整理成了一个开源项目。

目前项目仍在持续完善中，希望它能够帮助更多开发者将 uniCloud 应用到桌面软件和其他 JavaScript 项目中。

如果你也有类似需求，欢迎体验和交流。

项目地址： https://github.com/yungot/unicloud-sdk

npm： https://www.npmjs.com/package/@yungot/unicloud-sdk

—— yungot@qq.com