XuqmGroup React Native SDK

XuqmGroup 通用 React Native SDK 工作区。@xuqm/rn-common 是唯一基础包；其余扩展包都复用 common 的配置、初始化、会话、网络和通用能力。仅使用 common 时不放配置文件、不包装 Metro，也不要求初始化或登录；使用任一官方扩展时，由 withXuqmConfig() 在业务入口前自动启动一次共享上下文。

包结构

包	用途	可独立使用
@xuqm/rn-common	可选 SDK 上下文、网络、文件、时间、加密、设备与通用 UI	是，且无需初始化或登录
@xuqm/rn-update	App 更新、RN 插件注册、下载、校验与运行	否，依赖 common
@xuqm/rn-xwebview	WebView、JSBridge、权限与下载	否，依赖 common
@xuqm/rn-bugcollect	错误、事件、漏斗和批量上报	否，依赖 common
@xuqm/rn-im	IM 连接、消息和本地数据	否，依赖 common
@xuqm/rn-push	多厂商原生推送桥接	否，依赖 common

根包 @xuqm/rn-sdk 只用于仓库内聚合开发，不对外发布。应用应按需安装具体包，避免引入未使用的原生能力。

安装

项目 .npmrc：

registry=https://registry.npmjs.org/
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/

最小安装：

pnpm add @xuqm/rn-common axios \
  @react-native-async-storage/async-storage

按需增加扩展包，例如：

pnpm add @xuqm/rn-update @xuqm/rn-xwebview @xuqm/rn-bugcollect

common 独立使用

只安装 common 时，可以直接调用文件、时间、网络、加密、设备和 UI 能力，不要求配置、初始化或登录。apiRequest 使用绝对 URL，或先调用 configureHttp 配置基础地址即可。

扩展包一次初始化、一次登录

把平台生成的 config.xuqmconfig 放在 src/assets/config/，然后只包装一次 Metro 配置。使用 update 插件化时采用 update 组合器（它已包含 common 自动初始化）：

const { getDefaultConfig } = require('@react-native/metro-config')
const { withXuqmModuleConfig } = require('@xuqm/rn-update/metro')

module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))

不使用 update 时仍调用 @xuqm/rn-common/metro 的 withXuqmConfig()。两种组合器都会把初始化模块注册为 Metro pre-main module，避免 inlineRequires 延迟扩展包加载。应用登录成功后只更新一次公共会话：

import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.awaitInitialization()
await XuqmSDK.login({
  userId: 'user-id',
  accessToken: 'http-access-token',
  userSig: 'optional-im-credential',
})

await XuqmSDK.logout()

扩展包通过 @xuqm/rn-common/internal 接收同一次会话变化。宿主业务代码不得导入该内部子路径，也不得逐级传递公共 token 或用户状态。

平台签发配置与 Metro 自动初始化是扩展 SDK 的唯一初始化入口；不提供手动 initialize。common-only 宿主不放配置，也不初始化。

开发与验证

要求 Node.js 22、Corepack 和 pnpm 11：

corepack pnpm install
corepack pnpm validate

validate 会执行全部包的 TypeScript 校验和测试。开发 alpha 及正式包都只能由 Jenkins 发布到 Nexus，开发机不执行 npm publish。

集成 update 的宿主由 xuqm-rn start 和 xuqm-rn run android 统一代理 Metro 与 Android Debug 启动；宿主只保留简短的 start/android package script。

每个扩展包的安装要求与 API 以对应 packages/<name>/README.md 为准。整体设计见 docs/架构总览.md，公共接口见 docs/SDK-API参考.md。