Known Issues / 风险登记
May 21, 2026 · View on GitHub
表格按"严重度（P0/P1/P2）"排序；解决后移到底部"已关闭"区。
Open
| ID | 严重度 | 描述 | 出现版本 | 缓解 | 负责人 | 计划修复 |
|---|---|---|---|---|---|---|
| KI-001 | P2 | react-native-htmlview@0.16.0 仍依赖 deprecated PropTypes，需要 patches/ 兜底 | 0.80.x → 0.85.0（沿用） | patches 修补 | TBD | 后续替换为 react-native-render-html |
| KI-002 | P2 | @react-native-community/masked-view 已不再维护，社区推荐迁移到 @react-native-masked-view/masked-view | 0.80.x → 0.85.0（沿用） | 当前 patches 兼容 | TBD | 与 React Navigation v7 迁移合并执行 |
| KI-003 | P2 | react-native-i18n 走自建 fork，未来维护风险高 | long-term | 沿用 fork | TBD | 评估迁移到 react-i18next 单一栈 |
| KI-004 | P1 | RN 0.85.3 是最新 patch 但发布 < 15 天（红线），本轮升级取 0.85.0；待 0.85.3 满 15 天（约 2026-05-29 之后）再做 patch 升级 | 0.85.x | RFC §1.1.4 例外流程；正常等冷却期 | AI/Owner | 2026-05-29 后评估 0.85.3 |
| KI-005 | P2 | RN 0.85 推荐 Java 17 + Kotlin 2.1，已同步升级 build.gradle / app/build.gradle；本机 JDK 必须 ≥ 17 才能构建 Android（本机 OpenJDK 21 满足） | 0.85.0 | CI / 开发机统一 JDK 17+ | TBD | 文档已写入 upgrade-rn.md |
| KI-015 | P2 | RN 模板自带 tests/App-test.js 整 App 树渲染在 RN 0.85 + 项目三方栈（drawer-layout / i18n / root-toast / htmlview / lottie 等）下需要堆十几个 ESM transformIgnore 例外 + native module mock 才能 jest renderer.create()，性价比低。已 it.skip 并改用 Metro bundle smoke + Android 模拟器实跑 + utils/dao/store 单测等价覆盖。 | 0.85.0 | 跳过该 suite；其他 26 个单测全绿 | TBD | 下一轮按需引入 RNTL 重写为组件级测试 |
| KI-017 | P2 | scripts/check-package-age.js 对 git+https://... / URL / file: 形式的依赖一律返回 null → status skip，覆盖了 package.json 里 3 个 fork 的 git 依赖（react-native-i18n / react-native-spinkit-fix-new / react-native-version-number-fix-new），15 天冷却红线对它们形同虚设。同时 execSync('npm view ...') 用 shell 字符串拼接，遇到 >=1.0.0 <2.0.0 这种含空格的复合 range 会被 shell 解析错乱。 | 0.85.0 | 当前 3 个 git 依赖均为长期托管 fork，短期内不动；其它依赖均为 exact / ^semver 形态，不命中危险 range | TBD | 改 execFileSync 数组形式 + git+ 来源走 GitHub API commit author date 兜底 |
| KI-018 | P3 | 仓库根 build.gradle 与 android/init.gradle 都声明了 aliyun mirror，存在重复定义；init.gradle 没有被任何脚本（如 scripts/use-node.sh）默认通过 --init-script 注入，需要开发者手动 ./gradlew --init-script android/init.gradle <task> 才能生效 | 0.85.0 | 当前 build.gradle 内的 aliyun mirror 已经覆盖主链路；init.gradle 仅作可选兜底 | TBD | 二选一：要么删掉 init.gradle，要么写到 gradle.properties org.gradle.daemon.idletimeout 旁的 --init-script 默认注入脚本 |
| KI-020 | P3 | .github/workflows/ci.yml 的 Build job 与 Generate APK job 都跑 npx react-native build-android --mode=release，RN 0.85 默认走 bundleRelease（不触发 verifyReleaseResources），所以 patch 损坏 / lib 资源问题在 bundle 路径下被静默吞掉，只有 release 路径下 assembleRelease 才报错。建议把 Build job 也改成跑 :app:assembleRelease 或追加一步 :react-native-spinkit-fix-new:verifyReleaseResources :react-native-version-number-fix-new:verifyReleaseResources 强制覆盖 | 0.85.0 | 暂用本地 assembleRelease 在发版前做闸口；KI-019 修复后两条线一致 | TBD | 后续把 CI 步骤合并 / 加 verifyReleaseResources 显式调用 |
| KI-021 | P1 | android/build.gradle 的 buildscript.repositories / allprojects.repositories 把 maven.aliyun.com 镜像放在 google() / mavenCentral() 之前，GitHub Actions runner 在境外访问 aliyun CDN 偶发 502 Bad Gateway（CI run 26210555137 实证：Could not resolve com.google.code.gson:gson:2.11.0 → Received status code 502，叠加 68 个相同失败）。aliyun 一旦 502，Gradle 不会自动 fallback 到下一个 repo，导致整个构建挂掉 | 0.85.0 | 已修复：把 google() / mavenCentral() 提到 aliyun 之前作为主源，aliyun 镜像降级为国内开发机的兜底/加速。境外 CI runner 走官方源、国内开发机仍能命中 aliyun 缓存 | AI | 2026-05-21 |
Closed
| ID | 严重度 | 描述 | 关闭版本 | 关闭原因 | 关闭日期 |
|---|---|---|---|---|---|
| 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 |
