| KI-006 |
P0 |
RN 0.85 / Metro 0.84 要求 Node ≥ 20（Array.prototype.toReversed 等 ES2023） |
0.85.0 |
已通过项目级 Node 隔离方案解决：.nvmrc（20.19.4）+ package.json#engines + .npmrc engine-strict=true + scripts/use-node.sh（用 n exec 注入子进程 PATH，不动全局）。实测：项目内 npm run node:check → v20.19.4，npm run bundle:android:smoke → 4.7MB bundle ✔，npm run bundle:ios:smoke → 4.7MB bundle ✔；DevEco-Studio 内嵌 node 18 完全不受影响。进一步：@react-native-community/cli@20.1.3 engines >=20.19.4，所以 .nvmrc 从 20.18.1 升到 20.19.4。 |
2026-05-21 |
| KI-007 |
P1 |
已通过 Metro bundle:android:smoke / bundle:ios:smoke 双产物（各 4.7MB）端到端验证 JS 依赖图 + RN 0.85 + react 19.2.3 在 production 模式下能完整 transform。Android 原生层已实测：模拟器 Pixel_7 / API 36 / arm64-v8a 上 ./gradlew assembleDebug 成功（676 task，APK 219MB），adb install + monkey 启动后 Running "GSYGithubApp" {fabric:true}，登录页 OAuth 入口正常渲染。 |
0.85.0 |
Android 实跑通过 |
2026-05-21 |
| KI-008 |
P0 |
RN 0.85 二进制 ABI 静默 breaking 1：com.facebook.react.views.text.TextAttributeProps.UNSET 在 Kotlin 2.1.20 K2 编译器中无法被 import TextAttributeProps.UNSET（companion 成员直接 import）解析；命中 lottie-react-native@7.3.0 的 LottieAnimationViewPropertyManager.kt:23 |
0.85.0 |
已用 patches/lottie-react-native+7.3.0.patch 修复：把 import 改为 com.facebook.react.common.ReactConstants.UNSET（在 ReactConstants.kt:20 定义为 -1，与原值等价）。第八轮构建实测过 ✓ |
2026-05-21 |
| KI-014 |
P2 |
iOS smoke：pod install 一次跑通 93 pods（hermes-engine / RNReanimated 4.3 / RNScreens 4.24 / RNGestureHandler 2.31 / RNWorklets 0.8.3），xcodebuild Debug-iphonesimulator BUILD SUCCEEDED（修掉 project.pbxproj 残留的 -fmodule-map-file=DoubleConversion.modulemap 等老式 OTHER_CFLAGS / libDoubleConversion.a 死引用）。xcrun simctl install + simctl launch 起来 → WelcomePage → MainTabs / DynamicPage 正常渲染 GitHub received_events FlatList，token 登录链路 E2E 与 Android 等价闭环。 |
0.85.0 |
iOS 端实跑通过（fabric:true）；DynamicPage 渲染 8 条动态卡片成功（截图 /tmp/ios_smoke_main.png 实证） |
2026-05-21 |
| KI-016 |
P1 |
iOS Debug build 启动 SIGSEGV @ NULL：crash report 第 8 线程栈定位为 -[RealmReactModule injectModuleIntoJSGlobal] + 160 → facebook::jsi::Object::Object(facebook::jsi::Runtime&) + 32。根因：realm@20.1.0 / binding/apple/RealmReactModule.mm:67-69 写法 auto &rt = *static_cast<facebook::jsi::Runtime *>(bridge.runtime); 在 RN 0.85 + NEW_ARCH (bridgeless) 下 [RCTBridge currentBridge] 返回 nil，*static_cast<...>(nil) → 段错。 |
0.85.0 |
根因升级关闭（v5.0.1）：升级 realm 20.1.0 → 20.2.0（ADR-0004），realm 20.2.0 #7029 把 ObjC RealmReactModule.mm 取 bridge.runtime 的逻辑整体改为 pure C++ TurboModule，bridgeless 下不再走 [RCTBridge currentBridge] → 段错根除。删 patches/realm+20.1.0.patch 防御性绷带，app/dao/db/index.js 从 lazy require + 双层 noop 简化为正常 import Realm from 'realm' + 单层 try/catch logger.warn。Android emulator 装机实测 logcat Realm: setDefaultRealmFileDirectory + Absolute path: /data/data/com.gsygithubapp/files、pid alive、0 fatal ✓ |
2026-05-21 |
| KI-009 |
P0 |
RN 0.85 二进制 ABI 静默 breaking 2：RN 0.85 把 hermes-engine prefab 模块从 libhermes 改名为 hermesvm（见 hermes-engine/build.gradle.kts:441）。react-native-worklets@0.4.1 link hermes-engine::libhermes 失败 |
0.85.0 |
升级 worklets 0.4.1 → 0.8.3（2026-05-04，已满冷却 ✓） + reanimated 4.0.1 → 4.3.0（2026-03-25 ✓）。worklets 0.8.3 自身条件兼容 hermesvm/libhermes。第八轮构建实测过 ✓ |
2026-05-21 |
| KI-010 |
P0 |
RN 0.85 二进制 ABI 静默 breaking 3：facebook::react::ShadowNode::Shared 类型不再公开导出（YogaLayoutableShadowNode::Shared 仍在）。react-native-screens@4.13.1 的 C++ 头文件用了 ShadowNode::Shared |
0.85.0 |
升级 screens 4.13.1 → 4.24.0（2026-02-23，满 87 天 ✓）。第八轮构建实测过 ✓ |
2026-05-21 |
| KI-011 |
P0 |
RN 0.85 二进制 ABI 静默 breaking 4：shadowNodeFromValue 的返回类型从 std::shared_ptr<const ShadowNode> 改为 std::vector<std::shared_ptr<const ShadowNode>>。react-native-gesture-handler@2.27.2 的 cpp-adapter.cpp 在新类型上调用 getTraits() / getComponentName() 失败 |
0.85.0 |
升级 gesture-handler 2.27.2 → 2.31.2（2026-05-04，满冷却 ✓）。第八轮构建实测过 ✓ |
2026-05-21 |
| KI-012 |
P0 |
React 版本错配：RN 0.85.0 内部 react-native-renderer 锁定 19.2.3，但 package.json 声明 react: 19.2.5，运行时报 Incompatible React versions + TypeError: Cannot read property 'default' of undefined at PanGestureHandler 红屏 |
0.85.0 |
把 package.json 中 react / react-test-renderer 从 19.2.5 降到 19.2.3，跟 RN 0.85.0 内置 renderer 对齐。Metro reset cache 后实测 Running "GSYGithubApp" {fabric:true} ✓，登录页正常渲染 |
2026-05-21 |
| KI-019 |
P0 |
patch-package 双重静默失效：patches/react-native-spinkit-fix-new+1.1.4.patch 与 patches/react-native-version-number-fix-new+0.3.6.patch 同时存在两个 bug：(a) 早期手写 patch 头部为 --- a/x.orig +++ a/x（应为 --- a/x +++ a/x），patch-package 找不到 .orig 文件 静默 skip 不报错；(b) 用 npx patch-package <pkg> 重新生成时，因 node_modules 子目录里堆了 android/build/.transforms/ / bundleLib*Dex/ 等 Gradle 中间产物，被 patch-package 当成 "新文件" 全量打入 patch，单 patch 体积膨胀到 ~4.8MB / 5.4 万行，CI 干净环境 npm install 后 patch-package apply 失败（bundleRelease 与 assembleRelease 双线挂掉）。本机有缓存 build/ 时反而能通过，制造 "本地通过 / CI 失败" 假象 |
0.85.0 |
双修：(1) 头部 --- a/x 路径正确；(2) 重新生成 patch 前先 rm -rf node_modules/<pkg>/android/build 清掉构建产物，再 npx patch-package <pkg>。修复后 spinkit patch 4.8MB→2KB、version-number-fix-new 4.8MB→1.4KB。grep -l '\.orig' patches/*.patch → 0 命中、grep -l '\.transforms' patches/*.patch → 0 命中。本地 rm -rf node_modules && bash scripts/use-node.sh npm install 全新 install + npx react-native build-android --mode=release BUILD SUCCESSFUL 3m10s ✓ |
2026-05-21 |
| KI-022 |
P0 |
AGP 8.x namespace 与 Java 实际 package 错配：v5.0.0 第三次 CI run（commit c72e34c）Generate APK 阶段失败：PackageList.java:87: error: cannot find symbol class RNVersionNumberPackage location: package com.reactnativeversioncheck。根因：patches/react-native-version-number-fix-new+0.3.6.patch 在为 AGP 8.x 加上 namespace "com.reactnativeversioncheck"时拍脑袋取了一个新 namespace，但 node_modules/react-native-version-number-fix-new/android/src/main/java/com/apsl/versionnumber/RNVersionNumberPackage.java 第 1 行 package com.apsl.versionnumber; 才是真实 Java package。RN autolinking 在 PackageList.java 生成 import com.reactnativeversioncheck.RNVersionNumberPackage; 时按 namespace 推断 import 路径 → 编译期找不到符号。本地 build/ 缓存有旧 PackageList.java 时反而误通过 → "本地通过 / CI 失败"假象再次出现。属于 KI-019 复盘后第 4 个 patch-package 暗坑。 |
0.85.0 |
修 patches/react-native-version-number-fix-new+0.3.6.patch 把 namespace 改回 com.apsl.versionnumber（与 Java 实际 package 一致）。同时 sanity check spinkit：patches/react-native-spinkit-fix-new+1.1.4.patch namespace com.react.rnspinkit 与 RNSpinkitPackage.java 实际 package 一致 ✓。rm -rf node_modules && bash scripts/use-node.sh npm install + cd android && ./gradlew clean assembleRelease BUILD SUCCESSFUL in 2m51s，APK 42MB versionName 5.0.0，emulator 装机 pid alive / 0 fatal logcat / 登录页正常渲染（/tmp/gsy_release_v5_login.png）。同时把 checklist.md §8.1 加 namespace ↔ Java package 一致校验闸口 |
2026-05-21 |
| KI-013 |
P2 |
Android 15+/16 (API 35+/36) 模拟器首启弹 This app isn't 16 KB compatible. ELF alignment check failed. 系统对话框；点 OK 后系统用 page-size 兼容模式跑，不影响功能。精确根因（v5.0.0 实测）：unzip -j app-release.apk 'lib/arm64-v8a/*.so' + NDK llvm-readelf -lW <so> | grep LOAD 校验 18 个 .so 的 LOAD segment Align —— 17 个 .so（RN 自身 + reanimated/gesture/screens/spinkit/hermes/fbjni/...）全部 Align=0x4000 (16KB) ✅，仅 librealm.so 一个 Align=0x1000 (4KB) ❌ —— realm@20.1.0 是当前唯一不合规 .so，realm 20.x 没在它的 ndk-build/CMake 里加 -Wl,-z,max-page-size=16384。 |
0.85.0 |
根因升级关闭（v5.0.1）：升级 realm 20.1.0 → 20.2.0（ADR-0004），realm 20.2.0 #7019 在 ndk-build / CMake 里加 -Wl,-z,max-page-size=16384 → 出厂 librealm.so LOAD Align 直接 0x4000(16KB)。本地 cd android && ./gradlew assembleRelease BUILD SUCCESSFUL 9s，llvm-readelf -lW lib/arm64-v8a/librealm.so | grep LOAD 三段全 0x4000 ✓；APK 内 18/18 .so 全部 16KB 合规、0 BAD ✓。emulator 装机后无 16KB 系统对话框、无 fatal、realm 默认目录正常初始化 ✓ |
2026-05-21 |