revopush-setup

Revopush OTA 设置

将 Revopush OTA 更新集成到 React Native 或 Expo 应用中。Revopush 是一项托管式（SaaS）服务，可直接替代 Microsoft CodePush；JS API 和大多数原生配置完全相同，只有包名和服务 URL 不同。当前 SDK 系列（2.5.x/2.6.x）还支持自动差分（“diff”）更新——服务器只会发送变更的字节，无需任何配置。

**docs.revopush.org 是权威信息来源，且 Revopush 仅提供托管式服务。**始终使用托管服务器 https://api.revopush.org（API）和 https://app.revopush.org（控制面板）。Revopush 目前不提供可自托管选项——绝不要告诉用户将 SDK 或 CLI 指向他们自己的服务器。如果版本或步骤看起来已过时，请查阅最新文档。

**提示：**安装 SDK 后，它会在 node_modules/@revopush/react-native-code-push/docs/ 中附带权威设置文档（setup-android.md、setup-ios.md、api-js.md 等）。对于此处未涵盖的特殊情况（例如，非标准模板），请查阅这些文档；它们与已安装的版本完全一致。

适用场景

当开发者希望在 React Native 或 Expo 项目中添加或配置 Revopush/CodePush OTA 更新时使用。如果他们只想发布已集成应用的版本，则不要使用本指南——这种情况只需使用 revopush CLI（参见 references/cli-and-releases.md）。

安全规则

这些修改会涉及实际的原生项目文件。请保持操作透明：

1. 确认项目根目录——其中必须存在包含 react-native 的 package.json。如果不存在，请停止并询问应用所在的位置。
2. 先检测，再编辑。运行 scripts/detect-project.sh，并在进行任何修改前向用户展示检测到的 React Native 版本、Expo 与裸项目的判断结果、原生文件变体（Swift 或 Objective-C、Kotlin DSL 或 Groovy、Kotlin 或 Java），以及决定 MainApplication 配置方式的 Android 宿主模式。工作流会据此分支。
3. **谨慎编辑。**修改每个原生文件前，告知用户要修改哪个文件以及要添加什么内容；一次只编辑一个文件，以便于审查和还原。scripts/wrap-entry.js 辅助脚本会优先执行 --dry-run，并备份它修改的文件；请用它来包装 JS 入口。
4. **绝不编造部署密钥。**密钥需在控制面板 https://app.revopush.org 中创建（用户在该处注册并登录），或通过 CLI 创建。请向用户索取其 iOS 和 Android 密钥，或参照 references/cli-and-releases.md 引导他们获取。如果用户还没有密钥，只能将 YOUR_DEPLOYMENT_KEY 用作占位符，并告知他们必须在发布前填入密钥，否则发布无法正常工作。

工作流

1. 检测

从项目根目录运行 scripts/detect-project.sh，并向用户展示摘要。它会报告 RN 版本、使用的是 Expo 还是裸 RN，以及存在哪些 iOS/Android 源码变体。根据结果采取相应操作：

检测结果	操作
存在 Microsoft react-native-code-push	这是一次迁移。阅读 references/migration.md 并按其中说明操作（然后执行它指定的版本和原生步骤）。
React Native < 0.76	Revopush 要求 RN 0.76 及以上。告知用户升级 React Native，或在较旧版本中使用 Microsoft CodePush（https://github.com/microsoft/react-native-code-push）。**到此为止。**
Expo SDK < 52	Revopush 需要 Expo SDK 52 及以上。告知用户升级 Expo，或停止操作。
Expo SDK 52+	阅读 references/expo.md 并按其中说明操作。
裸 React Native 0.76+	阅读 references/versions.md 选择 SDK 版本，然后阅读 references/ios.md 和 references/android.md，根据检测到的变体进行原生代码修改。
不是 React Native 项目／未知	停止操作，并询问用户 React Native 应用在哪里。

如果应用依赖 expo，并且包含 ios//android/ 文件夹，detect-project.sh 会根据这些文件夹是否被 git 忽略来判定：

• 被 Git 忽略 → 它们是生成的：托管式 Expo（CNG）。使用 Expo 路径；可以安全运行 prebuild --clean。无需询问，继续操作。
• 已跟踪（已提交） → 情况不明确。询问用户：托管式应用使用 Expo 路径（prebuild --clean 会重新生成原生代码）；仅使用 expo modules 并手动维护 ios//android/ 的裸 RN应用使用裸 RN 路径，并且不得运行 prebuild --clean（这会覆盖其原生代码）。

2. 选择 SDK 版本并安装

阅读 references/versions.md，选择合适的 @revopush/react-native-code-push 版本。差分更新始终使用 2.x 系列（2.5.x/2.6.x）；新设置绝不要使用 1.x 系列。目前的对应关系：RN 0.76–0.82 → @2.5.1，RN 0.83+ → @2.6.x，RN < 0.76 → 不支持（使用 Microsoft CodePush）。然后安装：

• 裸 RN： npm install --save @revopush/[email protected]（0.76–0.82），或 @2.6.0/最新的 2.6.x（0.83+）——请参阅 versions.md。
• **Expo：**安装 SDK 和配置插件，并根据 Expo SDK 将两者固定为匹配的版本：SDK 52–54 → @revopush/[email protected] + @revopush/[email protected]；SDK 55+ → @2.6.0 + @1.1.0。不要依赖 expo install 自动解析版本——请参阅 references/expo.md 中的表格。

另建议用户安装或更新最新版本的 Revopush CLI（npm install -g @revopush/code-push-cli / npm update -g @revopush/code-push-cli）——请参阅 references/cli-and-releases.md。

3. 应用原生集成

• **裸 RN：**按照 references/ios.md 和 references/android.md 操作。选择与检测到的变体相符的章节——iOS 使用 Swift 或 Objective-C；Android 使用 Groovy build.gradle 或 Kotlin DSL build.gradle.kts，以及 Kotlin 或 Java MainApplication。对于 MainApplication 的 bundle 接线方式，根据检测结果中的 Android 宿主模式，选择 getJSBundleFile() 覆写（§3a）或无桥接的 jsBundleFilePath（§3b）——判断依据是是否存在 DefaultReactNativeHost，而非是否启用了 New Architecture。按照安全规则，使用自己的 Read/Edit 工具逐个文件应用修改。
• **Expo：**根据 references/expo.md 修改配置插件，然后运行 npx expo prebuild --clean。

4. 接通 JS 层

使用 codePush() 高阶组件包装根组件，这是最简单且正确的默认做法。

先找到正确的文件。 包装包含 export default <RootComponent> 的文件，而不是 index.js。对于裸 RN，通常是 App.tsx/App.js（裸项目的 index.js 是 AppRegistry.registerComponent(name, () => App)，没有默认导出——辅助脚本会正确拒绝处理）。对于 Expo Router，则是根目录下的 app/_layout.tsx。如果不确定，请检查 package.json 中的 "main"，并追踪它注册的组件。

然后使用 scripts/wrap-entry.js 执行可重复运行且会备份的修改：

node scripts/wrap-entry.js <path-to-root-component-file> --dry-run   # preview
node scripts/wrap-entry.js <path-to-root-component-file>             # apply

如需了解高阶组件选项，以及用户希望自行控制更新流程的高级用法（手动调用 codePush.sync()、checkForUpdate()、自定义下载/安装界面、进度回调），请阅读 references/js-api.md。

5. 部署密钥与发布

添加 iOS 和 Android 部署密钥，并参考 references/cli-and-releases.md 向用户说明如何发布。

6. 验证

首先运行静态完整性检查，并解决检查指出的所有问题：

node --version >/dev/null && scripts/verify-integration.sh   # from project root

检查会针对 SDK 依赖、原生接线、服务器 URL 和密钥、Podfile 15.5 以及 JS 包装报告 PASS/WARN/FAIL。继续之前，请修复任何 FAIL；WARN（例如占位密钥）则是提醒。

然后通过实际发布进行端到端验证——OTA“看起来失效”但实际并非如此的情况就发生在这一步：

• 构建 release 版本（OTA 不会应用于 debug/dev）：裸 RN 使用 npx react-native run-ios --mode Release --no-packager（或 Android release 变体）；Expo 则使用 dev/native 构建（Revopush 不适用于 Expo Go）。
• 做一个简单且可见的 JS 更改，然后发布到构建中使用的密钥所对应的部署环境：revopush release-react <app> <ios|android> -d Staging （参见 references/cli-and-releases.md）。
• 重新启动应用两次。 使用默认的 installMode: ON_NEXT_RESTART 时，更新会在首次启动时下载，只有在下一次启动时才会应用——只重新启动一次看不到任何变化，会让人误以为失败。请明确告知用户这一点。

仅在适用的分支中阅读各参考文档，以保持此工作流精简。