常见问题 FAQ

通用问题

开发者需要自己准备服务器吗？

不需要。构建产物打包为 ZIP 上传平台，平台负责托管和分发。

SDK 支持什么框架？

SDK 是框架无关的纯 JavaScript 库。原生 HTML、React、Vue、Svelte、Angular 均可使用。唯一要求是最终产物必须是以 index.html 为入口的纯静态资源。

本地开发如何调试？

const sdk = GeneratorSDK.init({
  appKey: 'app_xxx',
  env: 'test',  // 连接测试环境 API
})

用 vite dev、npx serve . 等任意静态服务器启动即可调试。

初始化与登录

init() 后 getStatus() 返回未登录怎么办？

SDK 初始化时会异步验证缓存的 token。init() 返回后验证可能尚未完成。请使用 sdk.auth.onChange() 监听最终登录状态：

sdk.auth.onChange((status) => {
  if (status.isLogin) {
    // 真正的登录状态
  }
})

onChange 和其他监听器如何取消？

所有 onChange 方法都返回取消监听函数：

const unsub = sdk.auth.onChange(callback)
unsub() // 取消

用户信息中的用户名字段是什么？

userName（不是 nickname），对应后端 userName 字段。

框架集成

在 Vue 3 中使用 SDK 实例需要注意什么？

使用 shallowRef + markRaw 避免 Vue 深度代理 SDK 内部对象：

import { shallowRef, markRaw } from 'vue'

const sdk = shallowRef(null)
sdk.value = markRaw(GeneratorSDK.init({ appKey: 'app_xxx' }))

积分与计费

credits.getBalance() 返回的字段名是什么？

返回 { quota: number }，不是 { balance: number }。与后端接口保持一致。

Billing 和 Credits 的区别？什么时候用哪个？

• Billing（推荐）：高层封装，自动处理免费次数→积分的降级逻辑，适用于导出/下载等标准操作
• Credits：底层积分操作，适用于需要直接扣除指定积分的自定义场景（如 AI 生成）

withBilling 的积分不足检查是同步还是异步的？

同步。withBilling 内部调用 billing.check() 基于缓存判断。确保在使用前至少调用过一次 billing.getUsage() 加载缓存。

免费时段内操作会发网络请求吗？

不会。billing.consume() 在免费时段内直接返回成功，不发起后端请求。

部署与上传

上传的 ZIP 包有什么要求？

• 入口文件必须为 index.html（位于 ZIP 根目录）
• 所有静态资源使用相对路径引用
• 不允许包含服务端代码
• ZIP 包大小限制：50MB

第一期开发者如何定义 appKey？

appKey 本质上是生成器的 id。开发者可以自己定义一个稳定的 id，只要同一个生成器始终使用同一个值即可。