更新日志
[3.10.1] 2026-09-23
- [Changed] Storage:传统模式恢复下发临时链接 TTL。
getTempFileURL的maxAge、createSignedUrl/createSignedUrls的expiresIn会传给后端。小于 1 或非整数拒绝;大于 3600 时警告后仍按原值下发。未传maxAge时不下发该字段。getPublicUrl固定按 600 秒换链 - [Changed] Storage:
uploadFile的fileContent作为filePath的兼容字段,类型与取值相同;同时传入时忽略fileContent并警告。GATEWAY PUT 的content-length优先由适配器测算,算不出时在签名前抛INVALID_PARAMS - [Deprecated] Storage:
uploadFile的method: 'post'标为废弃。POST 表单上传仍可用,调用时警告并提示改用默认的put - [Changed] 内置微信小程序适配器升至
@cloudbase/adapter-wx_mp@~1.4.0,支持 COS PUT 上传:默认put以文件体发送并带真实字节长度;post仍走wx.uploadFile
[3.10.0] 2026-09-18
- [Added] 新增
app.realtime():与 Supabase Realtime 兼容的 Broadcast / Presence / Postgres CDC 客户端。全量引入@cloudbase/js-sdk后即可使用;按需引入时注册registerRealtimeJs(@cloudbase/js-sdk/realtime-js)。文档型collection.watch()仍使用registerRealtime(@cloudbase/js-sdk/realtime),两者互不替代。详见 实时推送 - [Fixed] 云函数:GATEWAY 调用按 HTTP
statusCode判定成败,不再把成功响应里的data.code当成业务错误;非 2xx 时解析 JSON / HTML / 纯文本错误体,throw: false时返回{code, message, requestId}
[3.9.4] 2026-09-14
- [Fixed] Auth:取消
updateUser对 base64 / data URI 头像的拦截(回退 3.9.3);超过 200KB 的头像字段仍会拒绝 - [Changed] Storage:传统模式
getTempFileURL传入maxAge时控制台警告——该字段仅为兼容,不会据此生成下载链接,TTL 无效;内部downloadFile/createSignedUrl/createSignedUrls不再透传maxAge,避免误报。需要可控过期请改用 PG 模式app.storage.from(bucketId).createSignedUrl(path, expiresIn) - [Changed] Storage:类型定义 / JSDoc 标明传统模 式
maxAge/expiresIn不会生效
[3.9.3] 2026-09-10
- [Fixed] Auth:
updateUser拒绝传入 base64 / data URI 或超过 200KB 的头像,避免把文件内容写入用户资料;请先上传再传 URL - [Fixed] Storage:POST 上传签名强制走旧版 CLOUD_API,覆盖 GATEWAY 默认通道,避免网关通道下签名失败
[3.9.2] 2026-09-04
- [Fixed] 文档型数据库:升级
@cloudbase/database至 1.5.1,修复实时推送watch()query 双重序列化导致服务端反序列化失败(INIT_WATCHerrorCode=100003);新增toWatchQuery()将 canonical EJSON 转回 0.12.x legacy 编码,数字/日期/正则/_id/orderBy/limit等惯用调用方式无感兼容
[3.9.1] 2026-09-01
- [Changed] Auth:明确 OTP 校验两条路径的
messageId契约——signInWithOtp/signUp返回的data.verifyOtp回调无需传messageId(SDK 已缓存);独立调用auth.verifyOtp(含getVerification发码后)必须传messageId - [Changed] Auth:客户端缺参错误改为
missing_required_param(errorCode4000),错误信息带调用点与参数路径,例如auth.verifyOtp(params): missing required param 'messageId';与服务端invalid_argument/ 通道未配置(unimplemented)区分 - [Changed] Auth:类型定义 / JSDoc 标明成对 API 的
messageId必填差异(回调可选,独立调用必填) - [Fixed] Auth:
AuthError二次包装不再丢码,避免和 gRPCinvalid_argument混在一起 - [Fixed] 文档型数据库 GATEWAY adapter:
order/projection去掉 EJSON 数字标记($numberInt),改为网关要求的[{field,direction}]与纯 JSON 数值,修复Invalid order format - [Fixed] 文档型数据库:单文档查询识别扩展(裸
_id/$eq/$oid),_id等值走GET /documents/:docId;单文档更新/删除统一走批量端点;doc.set的merge:false映射为replaceMode:true - [Added] 文档型数据库:新增
modifyAndReturnDoc——updateAndReturn在_id等值时走单文档端点returnDoc,非_id条件降级批量更新 - [Changed] 文档型数据库:低层 handler 入参归一化,
query/data/projection兼容对象与 EJSON 字符串
[3.9.0] 2026-08-27
- [Added] Node 端对齐 v4 / node-sdk 形态:新增统一 throw 开关
config.throw(throwOnCode仅作为init时的别名,canonicalize 后删除;默认true)。支持实例级app.setThrowOnCode(value)与顶层自由函数联动;functions/storage/database的服务端业务错误与本地校验统一读取该开关,throw=false时返回{code, message, requestId} - [Added] 新增
CloudbaseError(继承Error):code/message/requestId可直接访问,对齐 Gateway 业务错误裸对象形状(e.code无需再JSON.parse) - [Changed] 文档型数据库适配 Gateway 2.0 引擎新接口名(
getDocument/insertDocument/modifyDocument等),并适配 EJSON 参数格式;send()支持透传单次请求timeout - [Changed] BREAKING 本地校验错误由 JSON 字符串
Error改为CloudbaseError(message为纯文本,e.code可直接访问) - [Changed] BREAKING
db.RegExp()内部结构由$regex/$options改为$regularExpression({pattern, options}) - [Changed] BREAKING Node 形态错误码
INVALID_PARAMS更名为INVALID_PARAM(对齐 v3 node-sdk) - [Changed]
@cloudbase/database升级至 1.5.0,依赖bson由 7 降为 6 - [Fixed] MySQL/RDB:兼容小程序等环境下
request.fetch返回的 header 为普通对象、缺少标准Headers.get()的问题,避免 PostgREST 客户端解析响应时抛错
[3.8.2] 2026-08-25
- [Fixed] 将 Node 可选依赖(
ws/jsonwebtoken/@cloudbase/signature-nodejs)写入optionalDependencies,默认安装即可使用 realtime watch、createTicket、V3 管理端签名,无需再手写依赖白名单 - [Fixed] Node ESM 构建将 Node 内置模块改为
node:前缀 external,避免消费方用 esbuild 打成 CJS 时import.meta被清空、SDK 回退到 Web adapter 并在初始化时报window is not defined - [Fixed] 发布包类型声明改为自包含(
prepack内联子包类型并改写为@cloudbase/js-sdk/<name>自引用),修复 pnpm 严格布局下skipLibCheck: false出现大量TS2307 - [Fixed] Auth:第三方登录改用
provider_id与provider_id_token,合并重复的SignInWithProviderRequest,同时兼容provider_token与 ID Token - [Added]
@cloudbase/realtime导出RealtimeWebSocketClient,便于单独使用@cloudbase/database时手动注入Db.wsClientClass - [Fixed] 并发 accessKey 凭证隔离:
CloudbaseRequest绑定到 app 实例,同 env 多次init()不再互相覆盖鉴权状态;getCredentials按 accessKey 去重,避免并发请求串用他人凭证
[3.8.1] 2026-08-20
- [Fixed] MySQL/RDB:兼容小程序等环境下响应头为普通对象、缺少标准
Headers.get()的问题,避免 PostgREST 客户端解析响应时抛错
[3.8.0] 2026-08-13
- [Changed] Node 环境密钥改为按需读取,环境变量(
TENCENTCLOUD_*/CLOUDBASE_APIKEY)不再写入 config 持久化缓存;优先级:显式传入 > 环境变量,每级内accessKey>secretId/secretKey。支持云函数进程复用下setenv即时生效;getSecretInfo改用当前实例 config,避免多实例串用 - [Changed] GATEWAY 端点新增
GATEWAY_URL支持,优先级serviceUrl>GATEWAY_URL;Gateway 调用也使用服务端注入 URL 控制,注入 URL 中的/admin路径替换为/v1 - [Fixed] Node 适配器存储上传二次签名:已携带 COS 预签名
Authorization时不再重复签 V3 并把 body 改写成 JSON,避免上传 400 - [Fixed] APIKEY 模式网关鉴权:有
accessKey时统一加Authorization: Bearer <accessKey>,避免请求裸奔依赖内网 IP 信任 - [Fixed] CBF 环境识别:
checkIsInScf补充TCB_CONTEXT_CNFG判断,避免每次请求都发 metadata 探测
[3.7.1] 2026-08-03
- [Fixed] Auth 事件去重,SIGNED_IN/SIGNED_OUT 统一由 oauth2client 管理,避免重复触发
- [Fixed] 首次登录 SIGNED_IN 回调未携带 user 信息
- [Fixed] 退出登录后 切回标签页误触发 SIGNED_IN
- [Changed] OAuth
getCredentials改为始终以 storage 为准,新增 BroadcastChannel/visibilitychange 跨标签页同步
[3.7.0] 2026-07-30
- [Changed] 工程化:monorepo 迁移至 Yarn 2 (Berry 4.18.0),内部包依赖改用
workspace:*协议,发布时自动解析为具体版本 - [Changed] 发布流程切换到 Lerna
independent版本模式,支持按包增量发布(改动@cloudbase/oauth时自动联动发布@cloudbase/auth与@cloudbase/js-sdk);各子包public化,可单独发布 - [Fixed] 移除
@cloudbase/oauth(CloudbaseOAuth构造函数)与@cloudbase/mysql(getEntity)中遗留的调试console.log - [Fixed]
@cloudbase/appNode 适配器补全getSecretInfo相关类型断言
[3.6.7] 2026-07-30
- [Changed] Auth 模块:验证码接口
getVerification的usage取值统一收敛为VerificationUsage枚举(EMAIL/RECOVERY/REAUTHENTICATION),signUp、signInWithOtp、resetPasswordForEmail、updateUser、reauthenticate、resend等场景不再使用字符串字面量,避免误传 - [Changed]
@cloudbase/oauth新增导出VerificationUsage枚举 - [Changed]
resend内部data的usage字段类型由string收紧为VerificationUsage
[3.6.5] 2026-07-28
- [Fixed] 根治使用方在浏览器 / SSR(Next.js、Nuxt 等)打包时因 Node 可选依赖(
jsonwebtoken、@cloudbase/signature-nodejs、ws)报Module not found: Can't resolve 'xxx'的问题:这些依赖改由内部optionalRequire在运行时按需加载,模块名以片段运行时拼接、require从宿主运行时获取,打包器静态分析阶段无法识别,因此不会去解析它们。使用方无需再配置next.config.js的serverExternalPackages或 webpack 兜底 - [Changed] Node 适配器的
wsClass改为 getter 懒加载:仅当实时能力(realtime / database)真正读取该属性时才加载ws,未用到实时能力的 Node 场景不会加载ws;并新增防重复标记,避免未安装ws时重复执行加载与重复打印安装提示
[3.6.4] 2026-07-24
- [Fixed] 自定义登录场景下用户通过
init({ env, auth: { credentials } })传入的私钥无法被createTicket读取的问题:getSecretInfo()此前仅从顶层config.credentials读取,现同时兼容config.auth.credentials(js-sdk 风格)与顶层credentials(node-sdk 风格)两种传法 - [Fixed]
dealNodeAdapterConfig()回填config.auth.credentials时会被空值覆盖的问题,改为保留用户显式传入的credentials;并修正其兜底值类型(ICredentialsInfo对象,无有效值时为undefined,不再用空字符串)
[3.6.3] 2026-07-17
- [Changed]
timeout默认值区分运行环境:Node.js 环境(云函数/云托管/自建服务器)默认不设置超时(不限制),以适配服务端长耗时请求;Web 等非 Node.js 环境仍默认 15000ms。显式传入timeout时以传入值为准 - [Changed]
NodeRequest未设置timeout时不再施加超时中断(download及createAbortController均按需启用超时),仅在显式传入timeout时启用 - [Changed] Auth
updateUser不再支持修改密码:传入password/new_password参数将抛出错误,请改用resetPasswordForOld(旧密码修改)、resetPasswordForEmail(验证码重置)或reauthenticate(重新认证后改密) - [Changed]
UpdateUserReq类型从基础请求中剔除password/new_password字段(标记为never)
[3.6.2] 2026-06-29
- [Fixed]
getSecretInfo()中顶层 secretId/secretKey 场景下sessionToken错误地从环境变量TENCENTCLOUD_SESSIONTOKEN取值,修正为从 config 顶层sessionToken字段取值 - [Fixed]
getSecretInfo()中config.auth场景下sessionToken错误地从环境变量取值,修正为从config.auth.sessionToken取值 - [Fixed]
NodeRequestV3 签名时secretId/secretKey/sessionToken取值逻辑修正为同时支持顶层配置和config.auth配置(config.auth优先级更高)
[3.6.1] 2026-06-29
- [Fixed] AI 模块:优先使用原生 Web Streams API(Node.js >= 18 / 现代浏览器),避免
web-streams-polyfill在高版本环境中的兼容问题 - [Fixed] 浏览器端 webpack 构建增加
resolve.fallback: { crypto: false },避免引入 Node.jscrypto模块的 polyfill - [Changed]
@cloudbase/database依赖bson版本从^7.1.1降级为^6.10.3 - [Changed]
@cloudbase/mysql及database的typescriptdevDependency 升级至^5.0.0 - [Changed]
@cloudbase/mysqltsconfig.esm.json 补充moduleResolution: "node"
[3.6.0] 2026-06-29
- [Fixed] 修复 Node 端构建时
webpack.DefinePlugin将process.env整体替换为静态对象,导致运行时无法读取TENCENTCLOUD_SECRETID、TENCENTCLOUD_SECRETKEY、SCF_NAMESPACE等环境变量的问题 - [Fixed]
getSecretInfo()改为从getCloudbaseContext()统一取值(而非直接getEnv()),确保 context 中的环境变量优先级正确 - [Fixed]
getCloudbaseContext()新增CLOUDBASE_APIKEY环境变量的采集 - [Fixed] AI 模块:Node.js 适配器非流式场景下
responseData已是 JSON 对象时,跳过 ReadableStream 解析直接返回结果
[3.5.4] 2026-06-25
- [Fixed] 修复 Node.js ESM 环境下初始化时
getWxDefaultAdapter返回空对象导致useAdapters调用isMatch()报TypeError: i is not a function的问题 - [Fixed] 修复 GATEWAY 模式下文档型数据库集合查询时,后端返回数据缺少
list字段导致formatResDocumentData报TypeError: Cannot read properties of undefined (reading 'map')的问题
[3.5.3] 2026-06-25
- [Added] App 实例新增
registerHost(host, protocol?)方法,一次性设置所有端点(CLOUD_API / GATEWAY),只需传入 host 地址自动拼接路径 - [Added]
cloudbase.app.App类型声明补充registerHost、getEndPointWithKey、registerEndPoint、registerEndPointWithKey、parseCaptcha实例方法 - [Added]
ai(options?)支持传入baseUrl参数自定义 AI 服务地址 - [Fixed] AI 模块支持
registerEndPointWithKey后端点动态变更自动生效(aiBaseUrl/aiBotBaseUrl改为动态 getter) - [Fixed] MySQL/RDB 模块支持端点动态变更,
registerEndPointWithKey后新请求自动使用最新 GATEWAY 地址 - [Fixed] Auth/OAuth 模块支持端点动态变更,
registerEndPointWithKey后认证请求自动跟随最新 apiOrigin
[3.5.2] 2026-06-24
- [Fixed] 修复 Node 服务端(secretId/secretKey 认证)场景下,
CloudbaseRequest.fetch因无oauthInstance导致请求失败的问题,使 RDB 等模块能正确通过底层NodeRequest的 V3 签名自动换取 access_token
[3.5.1] 2026-06-23
- [Added] Auth 模块新增
AuthErrorCode数字错误码枚举及AuthError.errorCode、retryAfter属性 - [Added]
AuthErrorCategory新增RATE_LIMITED、CAPTCHA_REQUIRED、CAPTCHA_INVALID、MFA_REQUIRED、PRECONDITION_FAILED、VERIFICATION_FAILED分类 - [Fixed] Auth
updateUser中verifyOtp校验失败时正确返回错误;仅在实际修改时触发USER_UPDATED事件 - [Fixed] 验证码发送补充
target: 'USER'参数;修复 abort 监听器泄漏、容错解析非 JSON 响应体
[3.5.0] 2026-06-23
- [Added] Storage 模块新增 Neo 环境对象存储能力,
app.storage.from(bucketId)返回全新对象存储客户端(上传/下载/删除/移动/复制/签名 URL 等) - [Added]
app.storage新增 Bucket 管理 API:listBuckets/getBucket/createBucket/updateBucket/deleteBucket - [Changed]
app.storage.from()无参仍返回ClassicStorageFileApi(行为不变);传入bucketId返回 Neo 对象存储客户端 - [Deprecated] 传统顶层云存储 API(
uploadFile/downloadFile/deleteFile等)标记为废弃,推荐改用app.storage.from(bucketId)新 API
[3.4.8] 2026-06-16
- [Fixed] 修复
getUser和getSession在无凭证或accessKey模式下返回user统一返回null
[3.4.7] 2026-06-16
- [Fixed] Auth 模块
verifyOtp的token参数兼容number和string类型
[3.4.6] 2026-06-12
- [Refactor] 重构 Node.js adapter 层,整合微信云开发相关请求逻辑(callWxOpenApi / callWxPayApi / callCompatibleWxOpenApi / wxCallContainerApi)
- [Fixed] 修复微信云开发 form-data 请求返回值格式与旧版不一致的问题,正确返回 Buffer 类型响应
- [Changed] request 模块新增 responseType: 'buffer' 支持,兼容二进制响应场景
[3.4.5] 2026-06-10
- [Fixed] 服务端 body 为 stream 时设置 duplex: 'half'
[3.4.4] 2026-06-10
- [Fixed] 服务端增加
bson依赖
[3.4.3] 2026-06-10
- [Fixed] 修复 Node.js 环境下调用 downloadFile 报
window is not defined的问题
[3.4.2] 2026-06-10
- [Fixed] 修复 bundledDependencies 子包版本号导致 yarn install 时从 registry 查找失败的问题
[3.4.1] 2026-06-10
- [Fixed] 修复 database 模块文档查询相关问题
[3.4.0] 2026-06-09
- [Changed] 移除 analytics 模块,不再随主包发布
- [Changed] 子模块随主包一起发布,不再单独进行模块独立版本更新
- [Added] 支持 sub-path exports 按需引入(如
@cloudbase/js-sdk/auth)
[3.3.13] 2026-05-29
- [Fixed] 修复云函数相关问题
[3.3.12] 2026-05-28
- [Fixed] 适配 v1/user/me 接口返回字段变化,hasPassword 改用 password === 'SET' 判断
[3.3.11] 2026-05-26
- [Fixed] 修复 _getCredentials 中 credentials 为空时访问 scope 属性报错的问题
[3.3.10] 2026-05-19
- [Changed] fetch 请求支持 withCredentials 参数控制是否携带鉴权信息
[3.3.9] 2026-05-08
- [Changed] endPointMode 默认值更新为 GATEWAY
[3.3.8] 2026-05-07
- [Added] getUser 支持从 providers 中匹配当前小程序 appId 对应的 open_id
[3.3.7] 2026-05-06
- [Fixed] getUser 返回用户信息支持 open_id 字段
[3.3.6] 2026-04-30
- [Added] 文档型数据库支持批量新增数据
[3.3.5] 2026-04-29
- [Added] 添加类型定义
[3.3.4] 2026-04-21
- [Added] database where条件支持事务
[3.3.3] 2026-04-17
- [Fixed] signUp 修复 phone_number 为空时格式化报错的问题
[3.3.2] 2026-04-13
- [Changed] getUser/getCurrentUser 支持 isRefresh 参数控制是否发请求获取最新用户信息,默认每次请求最新数据
[3.3.1] 2026-04-13
- [Added] getUser 支持读缓存和读接口数据可选
[3.3.0] 2026-04-08
- [Added] database 支持 http api
[3.2.2] 2026-04-02
- [Added] signInWithOtp 支持 emailRedirectTo
[3.2.1] 2026-03-24
- [Added] 增加帮助信息
[3.2.0] 2026-03-23
- [Added] 小程序手机号授权支持服务商类型小程序
[3.1.12] 2026-03-16
- [Fixed] node 模式下请求参数增加 envName
[3.1.11] 2026-03-16
- [Fixed] node 模式下 v3 签名兼容 headers 为空场景
[3.1.9] 2026-03-13
- [Added] 增强类型声明以及错误提示
[3.1.8] 2026-03-12
- [Fixed] 增加 storage 类型定义
[3.1.7] 2026-03-12
- [Fixed] getVerification 增加 phone_number 参数格式化
[3.1.6] 2026-03-12
- [Added] signInWithOtp 增加可选参数 options.shouldCreateUser 控制是否自动注册用户
[3.1.5] 2026-03-11
- [Changed] 完善 database 类型定义
- [Added] 异常时增加 requestId 返回
[3.1.4] 2026-03-11
- [Fixed] verifyOAuth 返回预设重定向地址
[3.1.3] 2026-03-10
- [Fixed] verifyOAuth 兼容 hash 地址