App Center CLI CodePush教程：6步实现React Native热更新与分阶段灰度
项目地址: https://gitcode.com/gh_mirrors/ap/appcenter-cli App Center CLI 是 Visual Studio App Center 提供的官方命令行工具，其中的 CodePush 模块可以让你在不发版的情况下，通过热更新（Hot Update）方式向线上用户推送 JS 代码修复与迭代。本教程带你用 6 步完成 React Native 应用的热更新发布，并实现安全的分阶段灰度（Rollout）策略，从 1% 小流量验证一路放量到 100% 全量用户。
第1步：安装 App Center CLI 并完成登录
首先安装 CLI 工具（需要 Node.js 18 及以上版本，见 package.json 中的 engine 声明）：
npm install -g appcenter-cli
然后执行登录，交互式环境会自动打开浏览器授权，CI 场景也可以用 --token 直接传入令牌：
appcenter login
登录成功后，令牌会保存到本地安全存储中（macOS 钥匙串 / Windows 凭据管理器 / 文件令牌库），实现逻辑位于 src/commands/login.ts 与 src/util/token-store/ 目录。
第2步：创建 Staging 与 Production 部署通道
CodePush 的发布以"部署（Deployment）"为单位管理。灰度发布的关键，就是建立测试通道与生产通道：
appcenter codepush deployment add Staging
appcenter codepush deployment add Production
创建成功后，CLI 会打印部署名称和对应的 Deployment Key，注意保存它（后续接入客户端 SDK 时需要用到）。命令实现参考 src/commands/codepush/deployment/add.ts。
💡 小技巧：不指定部署名发布时，默认目标是
Staging（见 codepush-release-command-base.ts），这正好符合"先测试、后上线"的灰度工作流。
第3步：一键发布 React Native 热更新到 Staging
进入你的 React Native 项目根目录，执行发布命令：
appcenter codepush release-react --deployment-name Staging --description "修复首页崩溃"
这一条命令背后做了很多事（源码见 src/commands/codepush/release-react.ts）：
- 自动检测当前目录是否为 React Native 项目，并校验 Staging 部署是否存在；
- 自动执行 JS Bundle 打包（iOS 默认
main.jsbundle，Android 默认index.android.bundle）； - 如果检测到 Hermes 已启用（Android 的
build.gradle或 iOS 的Podfile），会自动完成 JS 到字节码的编译； - 自动从
Info.plist或build.gradle读取目标二进制版本（target-binary-version），确保热更新只推给匹配版本的原生包； - 自动压缩并上传更新包，创建正式 Release。
整个过程无需手动打包，也无需手写版本号。
第4步：查看发布历史，确认灰度比例
发布完成后，用 history 命令确认更新已生效：
appcenter codepush deployment history Staging
输出中会展示每个 Release 的标签、描述、激活状态与活跃用户数；如果设置过灰度比例，还会以绿色高亮显示 Rollout: x%（见 src/commands/codepush/deployment/history.ts）。
第5步：promote 分阶段灰度，从小流量到全量放量
内部测试通过后，将 Staging 的最新 Release 原样提升到 Production，并用 --rollout 指定灰度百分比：
appcenter codepush promote -s Staging -d Production --rollout 25
随后观察线上指标（崩溃率、业务埋点等），逐步放量：
appcenter codepush promote -s Staging -d Production --rollout 50
appcenter codepush promote -s Staging -d Production --rollout 100
灰度的核心规则（源码见 src/commands/codepush/promote.ts 与 validation-utils.ts）：
--rollout取值必须是 1~100 之间的整数，超出范围会直接报错；- 可以用
--label指定要提升的历史版本，默认取源部署的最新 Release； - 如果新版本内容与当前线上完全相同，默认会报错，可加
--disable-duplicate-release-error将其降级为警告，方便 CI 流水线幂等执行。
第6步：出问题怎么办？一条命令紧急回滚
热更新最大的价值，就是快速修复与快速止血。一旦灰度期间发现线上异常，立即回滚到上一个稳定版本：
appcenter codepush rollback Production
执行前 CLI 会弹出确认提示防止误操作；如需回滚到指定标签，加上 --target-release 参数即可（实现见 src/commands/codepush/rollback.ts）。
小结：CodePush 热更新灰度工作流清单
| 步骤 | 命令 | 作用 |
|---|---|---|
| 1️⃣ 登录 | appcenter login | 授权 CLI 访问 App Center |
| 2️⃣ 建通道 | codepush deployment add Staging/Production | 分离测试与生产流量 |
| 3️⃣ 发更新 | codepush release-react -d Staging | 自动打包并热更新到测试通道 |
| 4️⃣ 看历史 | codepush deployment history | 确认版本与 Rollout 状态 |
| 5️⃣ 灰度 | codepush promote -s Staging -d Production -r 25 | 分阶段放量至 100% |
| 6️⃣ 回滚 | codepush rollback Production | 紧急回退到稳定版本 |
掌握这套流程后，你的 React Native 应用就具备了"当天上线、当天验证、随时回滚"的热更新能力。更多参数细节可以查看 appcenter codepush release-react --help，或深入阅读 src/commands/codepush/ 目录下的命令源码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
