UniApp 0.3.0 迁移指南¶

本文适用于从 0.2.x 升级到 0.3.0 及以上版本的项目。

请先确认项目的接入方式，只阅读对应章节：

• uni-app 应用：由 HBuilderX 直接构建 App，请阅读uni-app 应用迁移；
• 宿主 App 中的 uni 小程序：使用 uni-app 开发、制作为 wgt 资源包并运行在宿主 App 中，请阅读宿主 App 中的 uni 小程序迁移。

下文的 diff 代码块中，- 表示需要删除的内容，+ 表示需要新增的内容。

uni-app 应用迁移¶

0.3.0 新增 GC-UniPlugin UTS 插件，用于替换原有的 App 原生语言插件 nativeplugins/GCUniPlugin。升级时需要完成两项修改：替换插件，以及修改 SDK API 的导入方式。

1. 替换 App 原生语言插件¶

删除旧的本地原生语言插件，改为安装 GC-UniPlugin UTS 插件：

- nativeplugins/GCUniPlugin
+ uni_modules/GC-UniPlugin

迁移后的目录结构：

uni_modules/
├── GC-JSPlugin
└── GC-UniPlugin

同时完成以下操作：

1. 删除 manifest.json 中 nativeplugins/GCUniPlugin 对应的本地原生语言插件配置；
2. 从同一版本发布包复制 GC-JSPlugin 和 GC-UniPlugin，不要混用不同版本；
3. 使用 4.25.0 及以上版本的 HBuilderX。

如果从 0.2.0 至 0.2.3 升级，原项目中可能没有 GC-JSPlugin，迁移时同时安装这两个模块。

不要同时保留 nativeplugins/GCUniPlugin 和 uni_modules/GC-UniPlugin，否则可能产生重复 SDK、重复采集或原生符号冲突。

2. 修改 SDK API 导入方式¶

删除通过 uni.requireNativePlugin() 获取 SDK 对象的代码，改为从 GC-UniPlugin 导入：

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ // main.js / main.ts：仅加载一次，并放在 GC-JSPlugin 采集器调用之前
+ import '@/uni_modules/GC-UniPlugin/setup.js';
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-UniPlugin';

3. 原有初始化代码保持不变¶

完成 API 导入方式迁移后，原有初始化调用可以继续使用：

mobileAgent.sdkConfig(mobileConfig);
rum.setConfig(rumConfig);
logger.setConfig(loggerConfig);
tracer.setConfig(traceConfig);

仅需按下面的情况检查相关参数。

采样率参数¶

如果配置中使用了 samplerate，建议改为 sampleRate：

rum.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

logger.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

tracer.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

samplerate 当前仍兼容，但已废弃；同时设置时优先使用 sampleRate。

新增 HarmonyOS 应用¶

仅在发布 HarmonyOS 应用时，增加对应的 RUM App ID：

rum.setConfig({
    androidAppId: 'YOUR_ANDROID_APP_ID',
-    iOSAppId: 'YOUR_IOS_APP_ID'
+    iOSAppId: 'YOUR_IOS_APP_ID',
+    harmonyAppId: 'YOUR_HARMONY_APP_ID'
});

各平台应使用各自在观测云创建的 RUM App ID。

HarmonyOS 如需自动采集 Action，还需要在应用启动阶段调用：

gcActionTracking.startTracking();

4. 按需调整 JS 采集器¶

从 0.2.6 及以下版本升级并使用 Vue 3¶

Vue 3 需要将 createSSRApp() 返回的应用实例传入 gcViewTracking.startTracking()：

export function createApp() {
    const app = createSSRApp(App);
-    gcViewTracking.startTracking();
+    gcViewTracking.startTracking(app);
    return { app };
}

详见 View 自动采集。

从 gcRequest 迁移至 gcResourceTracking¶

gcResourceTracking 自 0.2.7 起提供，用于拦截标准 uni.request。如果项目仍在使用已废弃的 gcRequest，建议迁移至 gcResourceTracking；两种采集方式不要同时启用。详见 Resource 自动采集。

宿主 App 中的 uni 小程序迁移¶

本节中的“uni 小程序”特指使用 uni-app 开发、制作为 wgt 资源包并运行在宿主 App 中的项目。

0.3.0 调整了 App 原生语言插件的使用方式和发布位置：

  # uni 小程序项目
- nativeplugins/GCUniPlugin
  uni_modules/GC-JSPlugin

  # 宿主 App
- 从 nativeplugins/GCUniPlugin 获取宿主侧原生依赖
+ 从 dist/unimp-host-extension 获取 GC-UniPlugin 原生依赖库

uni 小程序项目不再需要 App 原生语言插件，也不安装 uni-app 应用使用的 GC-UniPlugin UTS 插件。宿主 App 仍需集成 Native SDK，并添加 dist/unimp-host-extension 中对应平台的 GC-UniPlugin 原生依赖库。

1. 调整 uni 小程序项目¶

1. 删除 nativeplugins/GCUniPlugin 及 manifest.json 中对应的 App 原生语言插件配置；
2. 将 GC-JSPlugin 目录整体替换为 0.3.0 及以上版本；
3. 不安装 GC-UniPlugin，也不加载 GC-UniPlugin/setup.js。

调整后的目录结构：

uni_modules/
└── GC-JSPlugin

这里只调整 SDK 依赖，不需要升级或改造 uni 小程序工程。如果原有代码直接调用 uni.requireNativePlugin() 获取 SDK 对象，还需要完成下一步修改。

2. 修改 SDK API 导入方式¶

移除 App 原生语言插件后，直接调用 uni.requireNativePlugin() 可能提示未找到原生插件，并返回无效对象，导致后续方法无法调用。改为从 GC-JSPlugin 导入 SDK API：

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-JSPlugin';

GC-JSPlugin 会检查宿主是否已注册对应的原生 Module；Module 不可用时，后续 API 调用会安全降级，避免中断业务代码。在未集成 GC-UniPlugin 原生依赖库的基座中调试时，控制台仍可能显示“当前运行的基座不包含原生插件，请在 manifest 中配置该插件”的通用提示。此场景无需重新配置 App 原生语言插件，原生能力需要在完成依赖集成的宿主 App 中验证。

3. 更新宿主 App 依赖¶

宿主 App 继续集成 Native SDK。将原来从 nativeplugins/GCUniPlugin 获取的宿主侧原生依赖替换为 dist/unimp-host-extension 中对应平台的 GC-UniPlugin 原生依赖库：

• Android：gc-uniplugin-<version>.aar；
• iOS：GC-UniPlugin-App.xcframework；
• HarmonyOS：GCUniPlugin.har。

GC-UniPlugin 原生依赖库用于向 uni 小程序运行环境注册 SDK Module，对应旧版 App 原生语言插件提供的宿主侧原生能力。

各平台的依赖及注册方式见宿主 App 集成。

升级后验证¶

完成升级并重新制作自定义基座或安装包后，检查以下项目：

• 应用中只初始化一次 Native SDK；
• 已启用的 RUM、Log 和 Trace 数据可以正常上报；
• uni-app 应用已删除旧原生语言插件，且 setup.js 早于 JS 采集器加载；
• uni 小程序宿主 App 在打开 wgt 前完成 Native SDK 初始化和 Module 注册；
• uni.request 的业务回调保持正常，已启用 Trace 时可以正常添加 Trace Header。

如无法调用 Native API，请参考故障排查。