@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 中上传敏感信息；可按组织安全流程提交脱敏日志。