157 行
4.0 KiB
Markdown
157 行
4.0 KiB
Markdown
# 安装与自动配置
|
||
|
||
## 环境要求
|
||
|
||
- React Native `0.76` 或更高版本
|
||
- Node.js 当前 LTS
|
||
- Android `minSdk 24` 或更高版本
|
||
- 使用原生模块时，需要标准 React Native 原生工程或完成 Prebuild 的 Expo 工程
|
||
|
||
SDK 当前以 Android 为完整验证平台。页面中明确标记为 Android 的能力不能据此推断为
|
||
iOS 已支持。
|
||
|
||
## 配置 npm 仓库
|
||
|
||
宿主从只读聚合仓库安装依赖：
|
||
|
||
```ini
|
||
# .npmrc
|
||
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/
|
||
```
|
||
|
||
请使用租户平台为当前应用推荐的精确版本。开发和测试阶段可能使用带 `alpha`、`beta`、
|
||
`rc` 或 `SNAPSHOT` 标识的预发布版本，不要自行改成无预发布标识的版本。
|
||
|
||
## 按需安装
|
||
|
||
只使用通用基础能力：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-common axios \
|
||
@react-native-async-storage/async-storage
|
||
```
|
||
|
||
使用版本更新：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-common @xuqm/rn-update \
|
||
@react-native-async-storage/async-storage
|
||
```
|
||
|
||
使用 WebView：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-common @xuqm/rn-xwebview \
|
||
react-native-webview react-native-safe-area-context react-native-svg
|
||
```
|
||
|
||
其他模块同样按需安装：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-bugcollect
|
||
pnpm add @xuqm/rn-im @nozbe/watermelondb
|
||
pnpm add @xuqm/rn-push
|
||
```
|
||
|
||
项目使用 npm 或 Yarn 时，可以使用等价安装命令；不要同时维护多份锁文件。
|
||
|
||
## 获取配置文件
|
||
|
||
使用扩展包时，在租户平台进入目标应用并下载配置文件。将下载文件原名放到：
|
||
|
||
```text
|
||
src/assets/config/<平台生成的文件名>.xuqmconfig
|
||
```
|
||
|
||
约束：
|
||
|
||
- 目录中只能存在一个 `.xuqmconfig`。
|
||
- 不要重命名内容、手工编辑或提交到公共仓库。
|
||
- 公有化和私有化平台生成的配置不能混用。
|
||
- 重新生成配置后，下一次构建必须使用新文件。
|
||
- Common 独立模式不要放置配置文件。
|
||
|
||
建议加入忽略规则：
|
||
|
||
```gitignore
|
||
src/assets/config/*.xuqmconfig
|
||
```
|
||
|
||
## 配置 Metro
|
||
|
||
没有启用插件化时，只包装一次 Common：
|
||
|
||
```js
|
||
// 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`：
|
||
|
||
```js
|
||
const { getDefaultConfig } = require('@react-native/metro-config')
|
||
const { withXuqmModuleConfig } = require('@xuqm/rn-update/metro')
|
||
|
||
module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))
|
||
```
|
||
|
||
两种配置二选一。项目只能存在一个 Metro 配置出口。
|
||
|
||
## Android 仓库
|
||
|
||
原生依赖从 XuqmGroup Android 聚合仓库读取：
|
||
|
||
```kotlin
|
||
// settings.gradle.kts
|
||
dependencyResolutionManagement {
|
||
repositories {
|
||
maven("https://nexus.xuqinmin.com/repository/android/")
|
||
google()
|
||
mavenCentral()
|
||
}
|
||
}
|
||
```
|
||
|
||
React Native 自动链接会处理已安装模块。只有 Update 插件化宿主需要按其页面说明应用
|
||
一次 Bundle 构建脚本。
|
||
|
||
## 启动前检查
|
||
|
||
```ts
|
||
import { XuqmSDK } from '@xuqm/rn-common'
|
||
|
||
const state = XuqmSDK.getInitializationState()
|
||
// idle | initializing | ready | degraded | failed
|
||
```
|
||
|
||
一般业务无需等待初始化。确实需要在首屏执行扩展操作时：
|
||
|
||
```ts
|
||
await XuqmSDK.awaitInitialization()
|
||
```
|
||
|
||
持续失败时按错误码展示非阻断提示，不要让 SDK 服务异常替代宿主首页。
|
||
|
||
## Debug 策略
|
||
|
||
- `pnpm start` 和 `pnpm android` 使用标准 Metro 与 Fast Refresh。
|
||
- Debug 默认不自动检查整包或插件更新。
|
||
- Debug 默认不自动上传 BugCollect。
|
||
- 需要验证服务时，通过对应模块的显式测试入口触发。
|
||
|
||
## 验收清单
|
||
|
||
- 工程中只有一份 `.xuqmconfig`。
|
||
- Metro 只使用一个 Xuqm 包装器。
|
||
- Common-only 工程不要求初始化。
|
||
- App 启动时没有手写 AppKey、平台地址或内部服务地址。
|
||
- 登录只调用一次公共会话入口。
|
||
- Release 构建使用租户平台当前有效配置。
|
