RN 插件脚手架

插件创建、构建、嵌入和发布统一由 @xuqm/rn-update 提供的 xuqm-rn CLI 完成。已删除独立 create-plugin.mjs，宿主不得复制 SDK 脚本或为每个插件维护一套构建命令。

初始化宿主

pnpm exec xuqm-rn init
pnpm check

init 只创建缺失的统一配置和必要脚本，不覆盖宿主已有代码。唯一插件构建清单为根目录 xuqm.modules.json。它与租户平台签发、宿主不可编辑的 config.xuqmconfig 初始化文件职责完全分离。

startup/common/app 与 Debug 插件的可重建胶水入口统一生成到 .xuqm/generated/entries。该目录必须加入 .gitignore，更换设备或主动删除后由 CLI/Metro 自动恢复；项目业务 bootstrap、页面和插件源码仍正常提交。

构建清单分别使用 packageName 保存 Android applicationId、使用 iosBundleId 保存 iOS Bundle Identifier。目标平台字段只在该平台 build/package/release 时必填。 ZIP wire 字段统一名为 packageName，但其值必须由 CLI 按平台从上述两个配置字段解析；发布时再与同一平台身份精确比较。

插件 ZIP v1 只有一套协议上限：归档不超过 50 MiB、单个 entry 解压后不超过 100 MiB、全部 entry 解压后合计不超过 100 MiB、entry 总数不超过 4096。CLI zipSync 只生成文件 entry，因此显式目录 entry 不属于 v1 协议，服务端和 Android stager 都必须拒绝；禁止在任一端另设 5000 等平行上限。

开发启动也使用同一 CLI，不由宿主复制 Node 包装脚本：

pnpm start
pnpm android -- --device emulator-5554

xuqm-rn start/run 始终调用宿主本地的 React Native CLI，并为子进程归一化 NO_COLOR/FORCE_COLOR 环境变量。

创建插件

pnpm exec xuqm-rn plugin create prescription

moduleId 必须：

以小写字母开头
只包含小写字母、数字和连字符
在 xuqm.modules.json 中唯一

CLI 会生成最小插件入口：

src/plugins/prescription/
  bundle.ts

并向 xuqm.modules.json.modules 增加唯一模块声明。不会修改 Babel alias、TypeScript paths、Metro offset 或增加模块专属 package script。

插件入口

生成的入口使用统一运行时定义，项目随后在该插件目录内实现自己的页面与导航：

import { definePlugin } from '@xuqm/rn-update'

definePlugin({
  moduleId: 'prescription',
  activate(context) {
    context.emit('plugin:ready', { moduleId: 'prescription' })
  },
})

插件入口不声明版本。默认 moduleVersion、commonVersionRange 和 minNativeApiLevel 由 CLI 从宿主 package.json.version、common 模块版本和 SDK 原生 API 等级一次性解析。

构建与发布

pnpm exec xuqm-rn doctor
pnpm exec xuqm-rn build android --module prescription
pnpm exec xuqm-rn publish android --module prescription

构建全部模块并嵌入宿主：

pnpm exec xuqm-rn embed android

生成 Android Release 安装包：

pnpm release:android
pnpm release:android -- --apk

Release 构建会先重新生成全部插件，不使用仓库内历史 bundle。

强制约束

不得在业务入口硬编码插件版本。
不得给同一插件同时维护 JSON、TS 常量和 package script 三套定义。
不得逐层传递 SDK 初始化、用户、token 或宿主运行时参数。
共通逻辑放在 common 或 update 运行时，不复制到各插件。
插件发布前必须通过 xuqm-rn doctor、宿主测试和 Release 构建。
.xuqm 不得保存人工源码或发布状态；删除后必须能够完整重建。

3.6 KiB 原始文件 Blame 文件历史