XuqmGroup-RNSDK/docs/插件脚手架.md

插件脚手架工具

脚本位置：packages/update/scripts/create-plugin.mjs
最后更新：2026-06-15

---

概述

create-plugin.mjs 是 UpdateSDK 提供的插件脚手架工具，用于一键创建完整的插件骨架项目。

功能：

• 交互式或命令行输入插件参数
• 校验 moduleId 唯一性
• 自动生成插件文件（bundle.ts / Screen / plugin.json）
• 自动注册到宿主（pluginCatalog / debugPlugins / build scripts / metro config / babel alias / tsconfig）

---

用法

命令行模式（推荐）

node scripts/create-plugin.mjs <moduleId> [title] [subtitle] [accentColor]

示例：

# 完整参数
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"

# 最简（title/subtitle/accentColor 使用默认值）
node scripts/create-plugin.mjs buz5

交互模式

node scripts/create-plugin.mjs

按提示依次输入 moduleId、title、subtitle、accentColor。

---

参数说明

参数	必填	格式	默认值	说明
moduleId	✅	^[a-z][a-z0-9]*$	—	插件唯一标识，如 buz4
title	❌	任意文本	= moduleId	插件标题
subtitle	❌	任意文本	{title}业务组件	插件副标题
accentColor	❌	CSS 颜色值	#0E84FA	主题色

---

自动生成的文件

插件目录 src/plugins/{moduleId}/

bundle.ts — 入口文件

import { UpdateSDK } from "@xuqm/rn-update";
import { registerPluginFromBridge } from "@plugins/runtimeBridge";
import { Buz4Screen } from "@buz4/Buz4Screen";

// 自动注册插件版本（bundle 加载时执行）
UpdateSDK.registerPlugin({ moduleId: "buz4", version: "1.0.0" });

// 注册 UI 组件到宿主运行时
registerPluginFromBridge({
  id: "buz4",
  title: "IM 消息",
  subtitle: "即时通讯业务组件",
  accentColor: "#E74C3C",
  Component: Buz4Screen,
});

{ModuleId}Screen.tsx — Screen 骨架

import { StyleSheet, Text, View } from 'react-native';

export function Buz4Screen() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>buz4</Text>
      <Text style={styles.subtitle}>TODO: 实现buz4功能</Text>
    </View>
  );
}

plugin.json — 插件元数据

{ "moduleId": "buz4", "version": "1.0.0" }

---

自动更新的宿主文件

文件	变更内容
src/app/pluginCatalog.ts	添加插件目录条目（id/title/summary/accentColor）
src/bootstrap/debugPlugins.ts	注册 debug loader（require('../plugins/{id}/bundle')）
package.json	添加 build:android:{id} / build:ios:{id} 脚本，更新聚合脚本
metro.split.config.js	添加 moduleId 的 offset 分支
babel.config.js	添加 @{id} alias
tsconfig.json	添加 @{id}/* path mapping

---

唯一性校验

脚本会检查两处来确保 moduleId 唯一：

1. src/app/pluginCatalog.ts 中已注册的 id
2. src/plugins/ 目录下已存在的目录名

如果 moduleId 已存在，脚本会报错并退出：

❌ moduleId "buz4" 已存在，请使用其他 ID

---

moduleId 命名规范

• 必须以小写字母开头
• 只能包含小写字母和数字
• 推荐格式：buz{N}（如 buz4、buz5）

Metro module ID offset 自动计算：buz1 → 11M，buz2 → 12M，buzN → (10+N)M。

---

创建后的开发流程

# 1. 生成插件骨架
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"

# 2. 实现业务 UI
# 编辑 src/plugins/buz4/Buz4Screen.tsx

# 3. 创建子目录
mkdir -p src/plugins/buz4/services
mkdir -p src/plugins/buz4/pages

# 4. 验证
yarn validate

# 5. 构建
yarn build:android:buz4
yarn build:ios:buz4