oh-my-hermes：一套提升 React Native 与 Hermes 排查效率的命令行工具库

以前我每接一个 React Native 项目都要先干三件事打开package.json看版本打开android/app/build.gradle找hermesEnabled再跑到真机上打印一下global.HermesInternal确认这套环境到底跑没跑在 Hermes 上。后来手上的项目多了光靠记忆实在靠不住——有的项目开的是新架构有的开了字节码有的还在用老式桥接每次配置问题都能耗掉一上午。所以我把这一串日常动作抽出来仿照 oh-my-zsh 的思路做了一个叫oh-my-hermes的本地效率工具库。它不是一个业务框架也不侵入项目代码就是一套拿到任何 RN 项目里都能用的 shell 函数和命令行工具。今天这篇就聊聊它是怎么设计的、核心命令怎么用以及在实践过程中踩到的那些坑。1. 被重复劳动逼出来的一个小项目为什么会有 oh-my-hermes1.1 每次换个项目都要重复问的三类问题如果你同时维护两三个 React Native 应用大概率遇到过这种场景新同事把仓库拉下来问你“咱们这个项目到底开没开 Hermes”你也没法拍脑袋答出来只能现场翻文件。我统计了一下自己日常至少有三分之一的时间浪费在这几类重复劳动上。第一类引擎开关状态。不同 RN 版本对 Hermes 的配置字段不一样老项目用enableHermes true新项目用hermesEnabled true。有些项目在升级过程中两个字段都出现过甚至被注释掉过光靠肉眼grep很容易误判。第二类release 包到底有没有真正走到 Hermes。很多团队做完一次发布根本没人去确认产物是不是 Hermes 字节码。它跟普通 JS bundle 长得不一样文件头有固定的魔数但你不会无聊到每次发布都去解包看四字节。第三类缓存问题。Metro 的缓存、Gradle 的缓存、Hermes 编译器缓存三个东西纠缠在一起一旦出现“改了代码但跑起来没变化”的诡异情况排查起来非常花时间。我之前升级一个老项目从 RN 0.64 一路升到 0.72构建日志里始终看不到 Hermes 相关的 task最后发现是android/app/build.gradle里旧字段enableHermes true被注释掉了而新模板用的是hermesEnabled true字段没对上Gradle 直接把 Hermes 配置忽略静默退回 JSC。这个案例直接促使我下决心把整套动作固化下来。1.2 为什么做成“oh-my-”这种形态而不是一个单脚本最早我写过一个check-hermes.sh跑完打印结果倒也够用。可一旦项目多了每个人 shell 环境不一样有的用 zsh有的用 bash有的连 PATH 都没配好一个孤零零的脚本很难做到“开箱即用”。oh-my-这个前缀本身就是从 oh-my-zsh 那边借来的心智。用户装完之后不是去调用某个绝对路径的脚本而是拥有一批像hm-check、hm-bundle这样随手可用的命令它们像插件一样按需加载不影响 shell 启动速度也不污染全局环境。换句话说oh-my-hermes 的定位是“一套轻量 shell 工具集 一组约定”。它本身不包含任何业务代码只负责把 React Native 开发里跟 Hermes 相关的脏活累活包起来让“检查引擎、打字节码包、清缓存”这些事情变成可复用的原子操作。2. 先搞清楚 Hermes 在你的项目里到底处于什么状态2.1 构建期检测Gradle 文件里的引擎开关要准确判断一个 RN 项目是否开启了 Hermes最直接的地方就是android/app/build.gradle。但这里有个细节不同 RN 版本的字段写法不一样而且同一份文件里可能有多个配置块你直接grep hermesEnabled不一定靠谱因为可能匹配到注释行。我在 oh-my-hermes 的hm-check里专门写了这个检测逻辑先去掉注释行再同时匹配新旧两种字段。核心就是下面这段hm_check_hermes_in_gradle() { local gradle_fileandroid/app/build.gradle if [ ! -f $gradle_file ]; then echo not a react-native android project return 1 fi if grep -vE ^\s*// $gradle_file | grep -qE hermesEnabled[[:space:]]*?[[:space:]]*true|enableHermes[[:space:]]true; then echo gradle: hermes enabled else echo gradle: hermes disabled or not found fi }这个grep -vE ^\s*//就是用来剔除被注释掉的旧配置。实测下来很有效能避免大量误报。另外还有一个更值得注意的点RN 0.70 之后Android 上 Hermes 已经是默认引擎了很多新模板里根本不显式写hermesEnabled而是靠默认值开启。这时候光读 Gradle 文件反而会误判。所以我把“版本号读取”也放进了hm-check先看package.json里react-native的版本再判断是否存在显式配置二者结合才能给出可靠结论。2.2 运行期检测HermesInternal 才是最强的印证构建期配置判断只是“纸面状态”最硬核的验证是让应用在运行时告诉你它到底跑在哪个引擎上。Hermes 暴露了一个全局对象HermesInternal只要运行环境是 Hermes它就一定存在。你可以在应用初始化代码里插一行console.log(Hermes?, !!global.HermesInternal); if (global.HermesInternal global.HermesInternal.getRuntimeProperties) { console.log(global.HermesInternal.getRuntimeProperties()); }这招在开发调试时非常有用。很多时候团队以为“开了 Hermes”但实际上某个构建变体跑的还是 JSC这种运行时判断可以直接揭穿真相。而且getRuntimeProperties()返回的内容里还带了不少字节码版本信息排查线上问题时能提供线索。不过要提醒一句这个判断必须在纯 JS 运行时环境执行不能放在打包工具脚本里。我之前见过有人尝试在 Node 环境里require(HermesInternal)那当然拿不到因为 Node 的运行时压根没有这个全局变量。2.3 产物验证字节码魔数骗不了人想让 release 包自己交代清楚最硬核的方式是直接看产物。Hermes 字节码文件的开头四个字节是固定的魔数c1 83 2a 9e普通 JavaScript bundle 不可能出现这个序列。操作方式很简单拿 apk 解包找到assets/index.android.bundle用xxd看文件头unzip -o app-release.apk -d apk_out xxd -l 4 apk_out/assets/index.android.bundle如果输出类似00000000: c183 2a9e那就不用争了这份产物确实用了 Hermes 引擎。我一般会在发布流水线里加这一步当作最后的“物证”防止 Gradle 配置被某些依赖库悄悄覆盖。3. 项目骨架与安装设计目录这么摆是有原因的3.1 仓库结构说明oh-my-hermes 的目录结构一开始就按“外部命令 内部库”的方式拆开不是把所有函数堆进一个文件里。这样有几个直接好处命令入口一目了然别人 clone 下来知道该看哪儿公共逻辑复用简单不会出现某个函数复制了三份、改了一处漏了两处的局面。oh-my-hermes/ ├── install.sh ├── init.zsh ├── hermes.plugin.zsh ├── bin/ │ ├── hm-env │ ├── hm-check │ ├── hm-bundle │ ├── hm-cache │ └── hm-perf └── lib/ ├── colors.sh └── common.shbin/下面每一个可执行文件都保持独立既可以当 shell 函数被 source也能作为脚本直接跑这一点对后面接 CI 非常关键。lib/里面放公共函数比如版本号解析、路径查找、终端颜色输出。init.zsh是加载器负责把所有能力挂到当前 shell 环境里。hermes.plugin.zsh这个名字是故意起的因为未来如果要把整个项目提交到 oh-my-zsh 的社区插件列表这是标准命名。3.2 install.sh 里最核心的几件事安装脚本并不复杂但有一个设计原则只追加加载逻辑不向/usr/local/bin复制任何文件。直接复制二进制很容易造成版本漂移你可能换个目录就想不起来这个工具到底是从哪儿来的。#!/usr/bin/env bash set -euo pipefail OH_MY_HERMES_HOME$(cd $(dirname ${BASH_SOURCE[0]}) pwd) SHELL_RC${HOME}/.bashrc if [ -n $ZSH_VERSION ]; then SHELL_RC${HOME}/.zshrc fi if ! grep -q oh-my-hermes/init.zsh $SHELL_RC; then echo [oh-my-hermes] adding loading snippet to $SHELL_RC cat $SHELL_RC EOF # load oh-my-hermes source $OH_MY_HERMES_HOME/init.zsh EOF else echo [oh-my-hermes] already installed fi这里有个细节判断当前 shell 用的是$ZSH_VERSION环境变量而不是直接echo $SHELL。因为很多人默认 bash但实际交互 shell 是 zsh光看$SHELL会被误导。这个小坑是我自己踩过之后才加上的。3.3 init.zsh 怎么做到 zsh/bash 双兼容加载器需要解决一个很实际的问题zsh 和 bash 获取当前脚本路径的方式不一样。zsh 里用${(%):-%N}bash 里用${BASH_SOURCE[0]}我直接在init.zsh里做了一个兼容判断# init.zsh case $(basename $0) in zsh) export OH_MY_HERMES_HOME$(cd $(dirname ${(%):-%N}) pwd) ;; *) export OH_MY_HERMES_HOME$(cd $(dirname ${BASH_SOURCE[0]}) pwd) ;; esac export PATH$OH_MY_HERMES_HOME/bin:$PATH source $OH_MY_HERMES_HOME/lib/common.sh source $OH_MY_HERMES_HOME/lib/colors.sh因为bin/下每个命令本身就是可执行脚本所以只要把bin/加进 PATH你在任意目录直接输入hm-check就能用不需要进入项目目录也不需要手动 source这才是“工具库”该有的体验。4. 命令设计每一个 hm-* 都是从真实工作里提炼的4.1 hm-check一键问诊项目状态hm-check是 oh-my-hermes 里使用频率最高的入口。它会一次性输出 RN 版本、Hermes 配置状态、本地编译器路径让你三十秒内了解当前项目情况。hm_check() { local root${1:-$(pwd)} echo RN version node -e const prequire($root/package.json); console.log(p.dependencies[react-native] || p.devDependencies[react-native] || unknown) echo hermes config in gradle hm_check_hermes_in_gradle echo hermesc binary find $root/node_modules/react-native/sdks/hermesc -type f \( -name hermesc -o -name hermesc.exe \) 2/dev/null | head -n 1 || echo not found echo runtime marker echo check global.HermesInternal in app runtime }运行效果类似下表的逻辑输出项含义一目了然输出项含义RN version判断项目使用的 RN 大版本辅助判断默认引擎hermes config in gradle显式配置的新旧字段状态hermesc binaryRN 自带编译器是否存在决定能否手动生成字节码runtime marker提示你在运行时用HermesInternal做最终确认我实际用下来这个命令最大的价值不是给老手用的而是给新同学。他们拿到一个陌生仓库第一件事不是翻文档而是跑一下hm-check当前项目的引擎状态就全出来了。4.2 hm-bundle手动生成字节码包的完整链路RN 项目在 Android 上开启 Hermes 后Gradle 构建流程会自动把 JS bundle 编译成字节码通常不需要手动干预。那为什么还要hm-bundle这个命令因为有些场景下你必须在 IDE 之外独立获得一份 hbc 产物比如分析 bundle 体积、验证字节码是否可生成、或者给 CI 提供可复现的制品。这就是hm-bundle存在的意义。hm_bundle_android() { local root${1:-$(pwd)} local output$root/build/hermes mkdir -p $output npx react-native bundle \ --platform android \ --dev false \ --entry-file index.js \ --bundle-output $output/index.android.bundle \ --sourcemap-output $output/index.android.bundle.map \ --assets-dest $output/res local hbc_path hbc_path$(find $root/node_modules/react-native/sdks/hermesc -type f \( -name hermesc -o -name hermesc.exe \) | head -n 1) if [ -z $hbc_path ]; then echo hermesc not found, skip bytecode compile return 1 fi $hbc_path -O -emit-binary \ -out $output/index.android.bundle.hbc \ $output/index.android.bundle }-O是开启优化-emit-binary是输出字节码文件。执行完这个函数你会在build/hermes下同时看到原始 JS bundle、sourcemap 和 hbc 三种产物非常适合做进一步分析。这里要特别强调一个容易误判的点Hermes 字节码的大小不一定比原始 JS 小。很多人一听到“编译成字节码”就以为体积会缩水实际不是这样。Hermes 的核心优势是省去了运行时的 JS 解析和编译阶段启动速度更快、内存占用更低体积变化往往不大甚至有些场景下会略微变大。如果你用体积来验收 Hermes 效果方向就错了。4.3 hm-cache区分浅清和深清的清理策略缓存问题几乎是每天都会遇到的。我在hm-cache里默认只做“浅清”也就是清理 Metro 缓存和临时目录绝不主动删 Gradle 目录——那属于重武器应该由人手动决定什么时候放出来。hm_cache() { local root${1:-$(pwd)} local mode${2:-shallow} echo cleaning metro cache... rm -rf $TMPDIR/metro-* 2/dev/null || true rm -rf $root/node_modules/.cache 2/dev/null || true if command -v watchman /dev/null 21; then watchman watch-del-all 2/dev/null || true fi if [ $mode --deep ]; then echo cleaning gradle build cache... (cd $root/android ./gradlew clean) fi echo done }为什么默认不执行./gradlew clean因为 Gradle 重新构建涉及大量依赖下载和增量编译清一次的成本可能是十几分钟起步。当遇到“改了原生配置但没生效”的情况绝大多数都是 Metro 的 JS 缓存问题先把$TMPDIR/metro-*和 watchman 缓存干掉重启 Metro基本能解决一半。只有确认是原生构建问题才值得动用--deep。4.4 hm-perf用两行命令对比产物指标hm-perf的功能相对轻量主要是在你打包完成后快速看一眼各种产物的体积和字节数方便前后对比。hm_perf() { local output${1:-$(pwd)/build/hermes} for f in $output/*.bundle*; do [ -e $f ] || continue ls -lh $f | awk {print $5, $9} done }这个命令还有一个隐藏用法给团队做 Hermes 接入前后的对比报告时直接甩出两张hm-perf的输出截图比任何宣传文案都有说服力。我去年给一个内部项目做引擎切换复盘就是靠这条命令整理了多组数据说明启动耗时下降了 35%而产物体积仅增加了几个百分点。5. 接入 oh-my-hermes 后最容易翻车的几个地方5.1 hermesc 版本错乱千万不要全局安装这是一个我踩得很深的坑。有段时间我在本机全局安装了一个 hermesc某次打字节码包时突然报错提示有无法识别的参数当时一度以为是自己写错了命令。查到最后才发现问题出在 PATH 的优先级上——系统找到了全局的旧版 hermesc而不是 RN 项目自带的那个。RN 自带的编译器位于node_modules/react-native/sdks/hermesc下按照平台分为osx-bin、linux64-bin、win64-bin等子目录。这个版本和项目里react-native的版本严格对齐晋级后必须同步更新。解法也很简单hm-bundle里直接用find从node_modules/react-native/sdks里找编译器完全不依赖 PATH。这也是为什么我在函数里不写hermesc而是写完整的查找逻辑。以后看到“hermesc 参数不识别”这类报错先查版本来源不要急着改命令。5.2 字节码和 sourcemap 的错位问题另一个容易翻车的点是 sourcemap。生成 Hermes 字节码的流程是先打出普通 JS bundle同时生成一份 sourcemap然后才用 hermesc 把 JS 编译成 hbc。编译过程不会改变源码行列关系所以线上错误堆栈还原时依赖的还是 bundle 阶段生成的那份 sourcemap。也就是说如果你在编译成字节码之后又单独重新生成了一份 sourcemap或者拷贝了别人的 map 文件那么堆栈反解出来大概率是错位的。这不是 Hermes 的问题而是打包流程设计本身就不严谨。我的建议是把 sourcemap 和 hbc 当作同一份构建产物来管理比如文件命名里带上 git commit hash 或时间戳确保 map 与字节码一一对应发布后归档到制品库不要随手散落在本地目录里。5.3 清理缓存的“过度治疗”有一次同事遇到“改完原生代码不生效”的问题情急之下执行了一整套“清理大法”删掉node_modules、删掉android/.gradle、删掉 Xcode 的 DerivedData然后把所有依赖重新安装了一遍。结果问题确实没了但光重新构建就花了接近半小时而且实际元凶只是 Metro 缓存里一个 sourceMap 的残留。这就是过度治疗。正确的优先级应该是先重启 Metro加--reset-cache重新启动。再清理$TMPDIR/metro-*和 watchman 缓存。如果问题涉及原生才执行./gradlew clean。最后才考虑删node_modules重装依赖。这个顺序我直接写进了hm-cache的设计理念里。工具应该是帮人做决策的而不是鼓励人把所有的重炮都轰出去。浅清和深清的分级本质上就是为了防止用户在没有判断依据的情况下过度清理。5.4 新架构与 Hermes 的叠加复杂度如果你用的是 RN 的新架构New ArchitectureHermes 几乎是必须搭配的引擎组合。这种场景下Gradle 配置字段会更多有时候hermesEnabled的设置会被多个地方影响比如react配置块、buildTypes、甚至 Gradle properties。遇到这种情况hm-check的输出只能作为参考最终要结合./gradlew :app:tasks的日志看有没有createBundleReleaseJsAndAssets或者 Hermes 编译相关的 task。这个排查思路已经超出工具本身属于“用工具辅助判断但保留人工确认”的工程素养。6. 团队复用与 CI 场景的下一步打算6.1 把命令固化到项目脚本oh-my-hermes 装完之后个人在终端里用很舒服。但团队协作时你不能要求每个人都去配置 shell 环境。一个折中方案是把常用命令挂进package.json的 scripts 里这样即使不 source 加载器也可以通过 npm 脚本调用。不过这里有个实现前提bin/下的每个脚本都必须是可独立执行的不能依赖 zsh 的加载逻辑。我在设计时已经想到了这一点所以每个hm-*文件开头都有 shebang内部自带参数解析。在项目里可以这样挂{ scripts: { hm:check: bash ~/.oh-my-hermes/bin/hm-check, hm:bundle: bash ~/.oh-my-hermes/bin/hm-bundle --platform android, hm:cache: bash ~/.oh-my-hermes/bin/hm-cache } }这样新同事即使还没安装 oh-my-zsh 或者没配置别的 shell 插件也能通过npm run hm:check快速了解项目状态。工具的“低门槛”往往体现在这些细节上。6.2 CI 里的冒烟检查接入 CI 是我目前觉得回报最高的一件事。你可以把hm-check放到 PR 流程里做一次引擎状态冒烟验证如果有人不小心把hermesEnabled true改成了falseCI 直接报错而不是等发布之后才在线上发现性能回退。更激进一点在 release 分支上跑hm-bundle把生成的 hbc 文件和 sourcemap 一起上传到制品库。这样每次发布的可复现性就有了保证线上出问题需要反解堆栈时直接去制品库拉同一 commit 对应的 map 文件。CI 里的 YAML 可以这样写- name: hermes smoke check run: | bash ~/.oh-my-hermes/bin/hm-check bash ~/.oh-my-hermes/bin/hm-bundle --platform android如果你担心 CI runner 上没装 oh-my-hermes可以考虑把整个仓库作为一个子模块放到项目里然后通过相对路径调用。反正bin/下的脚本没有任何外部依赖只要你机器上有 Node 和 RDK 环境就能跑这比依赖一个全局安装的工具可靠得多。6.3 后面还想加上去的几件事目前 oh-my-hermes 还只是覆盖了 Android 主战场。iOS 端的 Hermes 开关配置分布在 Xcode 工程文件和 Info.plist 里读取起来比 Gradle 麻烦一些但这块确实值得做。另一个我很想加的功能是hm-stack输入线上报错的原始堆栈配合本地 sourcemap 自动反解出源码行列这样排查问题时就不用再手动去翻 Symbolication 文档了。工具就是这样先从最痛的点下手用一阵子再迭代。如果你也维护着好几个 RN 项目建议先从hm-check这一条命令开始把“这个项目到底开没开 Hermes”这个每天都可能问一遍的问题彻底固化下来你一定会觉得值。