SDK 安装与升级说明
本文档给第三方工程师一个统一的安装与升级入口，覆盖当前已经正式发布的官方 SDK：
- React SDK：
@codebird/react - Go SDK：
github.com/lshaofan/codebird-go-sdk
当前推荐版本
截至 2026-03-17，当前推荐版本是：
- React SDK：
@codebird/react@0.4.3 - Go SDK：
github.com/lshaofan/codebird-go-sdk@v0.2.2
这两个版本已经覆盖了当前推荐接入模型中的关键能力：
- React SDK：
- 租户化终端用户入口 helper
- 实时会话上下文中的
tenant - 官方
CodeBirdAuthGuard - 短 TTL Access Token 自动续期
- refresh token 失效后的本地登录态清理
- Go SDK：
- Verifier
- 实时会话上下文客户端
- 租户化终端用户入口 helper
- M2M 组织成员管理客户端
- 当前正式支持的 5 个组织成员管理方法
React SDK
首次安装
bash
pnpm add @codebird/react@0.4.3升级到最新版本
bash
pnpm up @codebird/react升级后必须复核
- 是否已重启 dev server
- 是否实际使用到了新构建产物
- 是否仍然使用官方
CodeBirdAuthGuard - 是否还有自定义 token 过期判断
安装后优先阅读
Go SDK
首次安装
bash
go get github.com/lshaofan/codebird-go-sdk@v0.2.2
go mod tidy升级到最新版本
bash
go get github.com/lshaofan/codebird-go-sdk@latest
go mod tidy升级后必须复核
Issuer是否仍与前端endpoint一致Audience是否仍与前端defaultResource一致- 中间件或业务代码是否仍在手拆原始 claims
安装后优先阅读
如果你这次升级 Go SDK 的目的就是做组织成员管理，升级后应重点确认以下 5 个方法已经满足你的接入场景：
ListOrganizationMembersAddOrganizationMemberRemoveOrganizationMemberGetOrganizationMemberRolesUpdateOrganizationMemberRoles
当前推荐的前后端搭配
React 前端
- 统一使用
@codebird/react - 不自己维护
oidc-client-ts - 不自己写 refresh 逻辑
- 不自己写 token 过期守卫
Go 后端
- 统一使用
codebird-go-sdk Verifier负责验证用户 tokenClient负责实时上下文M2MClient负责服务端管理接口
什么时候应该升级
应升级 React SDK 的场景
- 登录、callback、Token 自动续期行为有变更
- 需要租户化终端用户入口 helper
- 需要官方认证守卫
- 需要修复短 TTL Access Token 场景
应升级 Go SDK 的场景
- 需要更稳定的 Verifier 能力
- 需要读取实时会话上下文中的
tenant - 需要服务端拼接租户化终端用户入口
- 需要组织成员管理能力
当前不建议继续沿用的旧接法
如果你的项目里还有这些接法，建议优先升级：
- 前端自己维护
oidc-client-ts UserManager - 前端直接调
/oidc/token - 前端自己根据
expires_at判断是否跳登录页 - 前端自己拼裸
/sign-in//account-center - 后端自己手写 JWT 验签与组织 claims 解析
升级后的最小验收清单
升级完成后，至少做下面几组联调：
1. 正常登录
预期：
- callback 成功
- 页面进入已登录态
2. Access Token 过期但 Refresh Token 仍有效
预期：
- SDK 自动续期
- 页面不跳登录
3. Refresh Token 过期
预期：
- SDK 清理本地状态
- 官方 Guard 触发未认证逻辑
- 第三方自动重新登录
4. 实时上下文
预期：
- 可以拿到
tenant.slug - 可以拿到最新
organization.is_admin