@hxa-rn/react-native-release-profiler

本项目基于 react-native-release-profiler 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

本库用于在 release 与生产构建中被动采集 JS/Hermes 性能数据，既可在本地复现具体性能问题，也可在生产环境收集性能采样。

• 通过 startProfiling() 启动 Hermes 采样会话，通过 stopProfiling() 结束会话并导出 .cpuprofile 文件。
• 支持将采样文件写入应用沙箱的 cache 目录或 Download 目录，并返回导出文件的绝对路径。
• HarmonyOS 端通过 TurboModule 调用 Hermes sampling profiler，导出的 .cpuprofile 可用 Chrome Tracing、Perfetto 或 SpeedScope 打开。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-release-profiler

库声明 react-native >=0.72、react 和 @react-native-community/cli-tools 为 peer 依赖，Node.js 要求为 >=18。

Autolinking

安装依赖后由宿主工程自动接入，无需手动注册。

导入

import { startProfiling, stopProfiling } from '@hxa-rn/react-native-release-profiler';

使用说明

基础用法

import { startProfiling, stopProfiling } from '@hxa-rn/react-native-release-profiler';

export async function profileSession(): Promise<void> {
  startProfiling();

  // 执行需要采样的业务逻辑

  const path = await stopProfiling(true, 'profile.cpuprofile');
  console.info(`profile saved to ${path}`);
}

startProfiling() 同步启动采样，stopProfiling(saveToDownloads, fileName) 异步结束采样并写出文件。saveToDownloads 默认值为 false，此时文件写入应用沙箱的 cache 目录；传入 true 时写入应用沙箱的 Download 目录。fileName 默认值为 profile.cpuprofile，只能是纯文件名。返回值是导出文件的绝对路径。示例工程提供启动、重复启动、分别保存到 Cache 与 Download、极短采样、默认参数导出和连续两次完整会话等场景入口。

连续会话与重复启动

import { startProfiling, stopProfiling } from '@hxa-rn/react-native-release-profiler';

export async function runTwoSessions(): Promise<void> {
  for (let index = 1; index <= 2; index += 1) {
    startProfiling();

    // 执行需要采样的业务逻辑

    const path = await stopProfiling(false, `session-${index}.cpuprofile`);
    console.info(`session ${index} saved to ${path}`);
  }
}

startProfiling() 在会话已激活时不会新建会话，仅记录告警后返回，因此同一时间只存在一个采样会话；stopProfiling() 在没有活动会话时会抛出错误。每次 startProfiling() 与 stopProfiling() 组合产出一个独立文件，可按上述方式连续执行多段采样。

接口文档

以下 API 依据 src/index.tsx 和 src/specs/v1/NativeReleaseProfiler.ts 整理。

导出 API

| API | 返回值 | 说明 | | --- | --- | --- | | startProfiling() | true | 同步启动 Hermes 采样会话。 | | stopProfiling(saveToDownloads?, fileName?) | Promise<string> | 异步结束采样会话，导出 .cpuprofile 文件并返回其绝对路径。 |

startProfiling()

同步启动 Hermes 采样会话，无参数。若会话已激活，则不再新建会话。

stopProfiling(saveToDownloads?, fileName?)

结束当前采样会话并写出采样文件。

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | saveToDownloads | boolean | false | true 时写入应用沙箱 Download 目录，false 时写入应用沙箱 cache 目录。 | | fileName | string | 'profile.cpuprofile' | 导出文件名，不能为空或包含路径分隔符。 |

| 返回值 | 类型 | 说明 | | --- | --- | --- | | 导出路径 | Promise<string> | 导出文件的绝对路径。 |

TurboModule 接口

入口导出基于 JS Spec 中的 TurboModule 注册名 ReleaseProfiler：

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | startProfiling | 无 | true | 启动 Hermes 采样。 | | stopProfiling | filename: string、saveToDownloads: boolean | Promise<string> | 结束采样并返回导出文件的绝对路径。 |

原生实现中另注册了 setFileExistenceCheckFailureForTesting 和 setFileWriteFailureForTesting 两个异常注入钩子，未在 JS Spec 与包入口中暴露。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | | :-- | --- | | Node.js | >=20 | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | API 21+ |

运行步骤

1. 获取开发分支源码：

   git clone -b react-native-release-profiler_dev https://gitcode.com/hxa-rn/react-native-release-profiler.git

2. 进入仓库根目录：

   cd react-native-release-profiler

3. 安装根目录依赖：

   npm i

4. 生成供示例工程安装的本地安装包：

   npm pack

5. 进入 example 目录：

   cd example

6. 安装示例工程依赖：

   npm i

7. 生成 React Native JavaScript Bundle：

   npm run dev

8. 使用 DevEco Studio 打开 example/harmony，同步依赖并完成签名配置后构建运行。

约束与限制

兼容性

| 依赖 | 要求 | | --- | --- | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | API 21+ | | Example 工程 compatibleSdkVersion | 6.0.1(21) | | Example 工程 targetSdkVersion | 6.1.1(24) | | Node.js | >=18；运行 Example 要求 >=20 |

使用限制

• 本包为 HarmonyOS 适配版本，发布内容仅包含 dist/、src/、harmony/、README.md 和 LICENSE，不包含上游的 Android、iOS 与 Web 实现。
• 仅支持 Hermes 引擎：在非 Hermes 运行时调用 startProfiling() 或 stopProfiling() 会抛出错误。
• stopProfiling() 的 fileName 只能是纯文件名，为空或包含路径分隔符时抛出错误。
• saveToDownloads 为 true 时写入应用沙箱内的 Download 目录，为 false 时写入应用沙箱内的 cache 目录，两者均为应用沙箱路径。
• 未启动会话时调用 stopProfiling() 会抛出错误；重复调用 startProfiling() 不会新建会话，仅记录告警。
• 导出后原生侧会检查文件存在且非空，失败时返回 rejected Promise 并清理未完成的文件。
• 上游 npm 包提供的 react-native-release-profiler CLI 未在本包中暴露（package.json 未声明 bin）；该 CLI 依赖 adb 与 Android 工程配置。导出的 .cpuprofile 可用 Chrome Tracing、Perfetto 或 SpeedScope 打开。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

开源 License

本项目采用 MIT，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。