xuqmGroup/XuqmGroup-Web

派生 0

XuqmGroup eb2baae07e docs(rn): rebuild public sdk documentation

2026-07-29 02:43:17 +08:00

4.0 KiB

原始文件 Blame 文件历史

安装与自动配置

环境要求

React Native 0.76 或更高版本
Node.js 当前 LTS
Android minSdk 24 或更高版本
使用原生模块时，需要标准 React Native 原生工程或完成 Prebuild 的 Expo 工程

SDK 当前以 Android 为完整验证平台。页面中明确标记为 Android 的能力不能据此推断为 iOS 已支持。

配置 npm 仓库

宿主从只读聚合仓库安装依赖：

# .npmrc
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/

请使用租户平台为当前应用推荐的精确版本。开发和测试阶段可能使用带 alpha、beta、 rc 或 SNAPSHOT 标识的预发布版本，不要自行改成无预发布标识的版本。

按需安装

只使用通用基础能力：

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

使用版本更新：

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

使用 WebView：

pnpm add @xuqm/rn-common @xuqm/rn-xwebview \
  react-native-webview react-native-safe-area-context react-native-svg

其他模块同样按需安装：

pnpm add @xuqm/rn-bugcollect
pnpm add @xuqm/rn-im @nozbe/watermelondb
pnpm add @xuqm/rn-push

项目使用 npm 或 Yarn 时，可以使用等价安装命令；不要同时维护多份锁文件。

获取配置文件

使用扩展包时，在租户平台进入目标应用并下载配置文件。将下载文件原名放到：

src/assets/config/<平台生成的文件名>.xuqmconfig

约束：

目录中只能存在一个 .xuqmconfig。
不要重命名内容、手工编辑或提交到公共仓库。
公有化和私有化平台生成的配置不能混用。
重新生成配置后，下一次构建必须使用新文件。
Common 独立模式不要放置配置文件。

建议加入忽略规则：

src/assets/config/*.xuqmconfig

配置 Metro

没有启用插件化时，只包装一次 Common：

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { withXuqmConfig } = require('@xuqm/rn-common/metro')

const config = mergeConfig(getDefaultConfig(__dirname), {
  // 宿主自己的 Metro 配置
})

module.exports = withXuqmConfig(config)

启用 RN 插件化时使用 Update 提供的组合器，不要再叠加 withXuqmConfig：

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

module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))

两种配置二选一。项目只能存在一个 Metro 配置出口。

Android 仓库

原生依赖从 XuqmGroup Android 聚合仓库读取：

// settings.gradle.kts
dependencyResolutionManagement {
  repositories {
    maven("https://nexus.xuqinmin.com/repository/android/")
    google()
    mavenCentral()
  }
}

React Native 自动链接会处理已安装模块。只有 Update 插件化宿主需要按其页面说明应用一次 Bundle 构建脚本。

启动前检查

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

const state = XuqmSDK.getInitializationState()
// idle | initializing | ready | degraded | failed

一般业务无需等待初始化。确实需要在首屏执行扩展操作时：

await XuqmSDK.awaitInitialization()

持续失败时按错误码展示非阻断提示，不要让 SDK 服务异常替代宿主首页。

Debug 策略

pnpm start 和 pnpm android 使用标准 Metro 与 Fast Refresh。
Debug 默认不自动检查整包或插件更新。
Debug 默认不自动上传 BugCollect。
需要验证服务时，通过对应模块的显式测试入口触发。

验收清单

工程中只有一份 .xuqmconfig。
Metro 只使用一个 Xuqm 包装器。
Common-only 工程不要求初始化。
App 启动时没有手写 AppKey、平台地址或内部服务地址。
登录只调用一次公共会话入口。
Release 构建使用租户平台当前有效配置。

4.0 KiB 原始文件 Blame 文件历史 Unescape Escape