前言版本口径2026-10当前正式发布版为Flutter OH 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter配套DevEco Studio 26.0.0 Release与OpenHarmony SDK / API 26。本篇是 2026-093.44.9 → 3.47.4批次的 Phase 12 实录命令与验证方法对 3.47.8 线同样适用。环境搭建见Flutter OH 环境搭建指导。第 5 篇给了生产侧的总图全新分支 三方重放不 merge五阶段、五道验证门。本篇放大Phase 1基线建立与 Phase 2Framework 适配两个阶段的实操细节——它们是整条流水线的地基也是本批次踩坑最「前置」的两个阶段Phase 1 的最大坑本地代理杀死 HTTP/2 大包传输全量 clone 两次失败一行git config解决Phase 2 的最大发现Dart SDK 必须从源码构建——给缓存目录里的 dart-sdk 打补丁是「零影响」的假动作补丁集也从 3 文件迭代到 6 文件。这两段内容对任何要做「上游同步」的分叉维护者都是通用经验不依赖本项目的具体版本号。全部操作取自 2026-09-13 批次实录macOS 15.4.1 arm64 新机。前置阅读第 5 篇的基线表四个坐标与清单概念。本篇从「四个坐标已核验」开始。一、Phase 1基线建立G1 门1.1 网络修障在前代理杀死 HTTP/2 大包基线建立的第一步不是 clone而是修网络。全量 clone 连续两次失败报错签名curl 18: transfer closed with outstanding read data remaining error: RPC failed; curl 56 fatal: early EOF小请求全部正常只有大包传输断裂——根因是本地代理127.0.0.1:1087杀死 HTTP/2 大包传输。修法是强制 git 走 HTTP/1.1gitconfig--globalhttp.version HTTP/1.1修复后 shallow clone 与 github 大包 fetch 全部一次通过。建议只要本机有 HTTP 代理就把http.versionHTTP/1.1设为永续全局配置——这是本批次「最前置」的坑不修它后面每一步都在重复失败。1.2 浅克隆分叉仓库 挂 upstream remotegit-chttp.versionHTTP/1.1 clone--depth1--single-branch\--branchoh-3.44.9-dev https://atomgit.com/oh-flutter/flutter_flutter.gitcdflutter_fluttergitremoteaddupstream https://github.com/flutter/flutter.git三个决策点--depth 1 --single-branch只取oh-3.44.9-dev的 tip17400 文件工作树 235MB / .git 42MB——全新分支方案不需要鸿蒙侧历史树级 diff 不受影响挂upstreamremote后续所有上游 tag 都从它 fetch不碰 origin 的引用空间HEAD 核验clone 完先对 HEAD本批次fe316cf7✅与旧机调研一致再往下走。1.3 拉取上游两个 taggitfetch--depth1upstream\refs/tags/3.47.4:refs/tags/3.47.4\refs/tags/3.44.9:refs/tags/3.44.9拉下来对 SHA第 5 篇 2.1 节基线表3.47.49584c6713b324636289d067944a46fd6b49df14b✅3.44.96b182d2c7585eba26d4edce0f97630effd256c33✅两个 tag 的用途不同3.47.4是新基线第 1.4 节3.44.9是适配清单的 diff 起点第 1.5 节——两个都缺一个Phase 1 就不算完成。1.4 创建基线分支gitcheckout-boh-3.47.4-dev3.47.4# HEAD 9584c671 ✅分支命名沿用oh-上游版本-dev风格release 分支在发布时切。此后这个分支上的一切改动都是「适配重放」的产物不混入任何 merge——第 5 篇 2.3 节三条理由在这里开始兑现。1.5 适配清单恢复与校验用「上游旧基线 ↔ 鸿蒙旧分支」的树级 diff 恢复适配清单gitdiff--name-status3.44.9 oh-3.44.9-devsync-data/ohos_adapt_list.txtwc-lsync-data/ohos_adapt_list.txt校验结果与旧机调研值逐项对账指标旧机调研值新机实测结论总文件22632263✅新增 A / 修改 M / 删除 D1738 / 522 / 31738 / 522 / 3✅行 / -行192740192740 / -2018✅顶层分布—engine 826 · dev 633 · packages 421 · examples 265 · ci 41 · 其他 ~80新增G1 验证门通过旧机全部研究数据在新机可复现sync-data/ohos_adapt_list.txt成为整批次的权威清单第 5 篇 3.6 节讲的三个读法都作用在这个文件上。浅克隆 树级 diff 是无损的——2263 文件清单一个不少。后续如需鸿蒙侧历史git log/blame写文档再git fetch --unshallow origin代价 GB 级 时间不必提前付。1.6 Phase 1 验收卡把 Phase 1 的五个动作与验收判据收进一张卡过这张卡G1 门才算数步骤动作验收判据1网络修障HTTP/1.1一次fetch --depth 1大包成功2浅克隆 挂 upstream工作树 235MB / .git 42MBHEAD 对账 ✅3fetch 两个上游 tagSHA 与基线表逐项一致 ✅4checkout -b oh-3.47.4-dev分支 HEAD 3.47.4tag 的 SHA5树级 diff 恢复清单2263 文件 / A-M-D / 行数 四项与旧机调研值全对上G1 门的本质让「清单」先于「重放」成为权威。清单不校验就开重放等于在没有地图的地方开车——错一行Phase 2/3 全跟着错。二、Phase 2Framework 适配421 文件三方重打2.1 git apply --3way0 冲突标记但别信「干净」从清单里圈出 packages/ 工作集421 文件以新基线为三方基准重放# 从权威清单圈出 Phase 2 工作集排除删除项awk$1 ! D(grep-E^[AMD].*packages/sync-data/ohos_adapt_list.txt|awk{print $3})# 以基线版本为三方基准三方合并gitapply--3waypackages 子集 diff重放后的真实状态有两层只看第一层会误判磁盘上0 个冲突标记没有——看起来「干净」但14 个文件停留在 unmerged 索引态——内容已经正确git 只是没确认# 找出停在 unmerged 态的文件gitdiff--diff-filterU --name-only# 内容正确直接确认gitadd上述文件「磁盘 0 冲突」≠「合并完成」。git apply --3way的 3-way 结果可能把冲突静默解决后留在索引里必须用git diff --diff-filterU逐个确认——「以为合完了」是三方重放的第一大假象。2.2 pubspec两处路径依赖改指本地 fork重打完还要处理flutter_tools/pubspec.yaml的两处路径依赖code_assets与hooks_runner改指本地 forkfluttertpc_dart_native/pkgs/保证 dart native hooks 的 ohos 支持与 3.47.4 的 hooks 1.5.0 API 一致dependencies:code_assets:path:../fluttertpc_dart_native/pkgs/code_assets# 本地 forkhooks_runner:path:../fluttertpc_dart_native/pkgs/hooks_runner# 本地 fork这一步不做的后果pub 会解析上游版本的 hooks 包与 3.47.4 的 API 对不上工具链在构建期才炸——比编译期报错晚一个阶段排查成本翻倍。三、本阶段最大发现Dart SDK 必须从源码构建Phase 2 真正的硬骨头不在 421 文件而在工具链的隐藏依赖定制 Dart SDK 不能「打补丁」必须从源码构建。本节是这个发现的完整链条也是最值得生产侧读者精读的部分。上图就是本节的全景上半是「正确路径」五步clone Dart 源码 → 6 文件补丁集 → 构建 patched_sdk → framework 用它编译 → sky_engine/lib 同步与验收判据左下是「错误路径」的三连击改缓存 dart-sdk 零影响 → JIT 内嵌 platform kernel → 症状不变右下是 421 文件三方重放的冲突形态0 冲突标记但 14 个 unmerged。底部结论一句话Dart 层是「源码构建」问题不是「改缓存文件」问题补丁集要 6 个文件不是 3 个。3.1 「打补丁缓存」为什么是零影响现象把 3.12.2-ohos SDK 的三个 ffi 补丁abi.dart、abi_specific.dart、ffi_patch.dart打到官方 3.13.3 的bin/cache/dart-sdk上然后验证import dart:ffi; print(Abi.ohosArm); // Member not found: Abi.ohosArm还是Member not found——补丁「打了个寂寞」。根因dartJIT 二进制内嵌了 platform kernel——lib/ffi、lib/_internal/vm/lib/ffi_patch.dart等源文件在构建期就编译进了 vm_platform 固件。改 SDK 仓库里的 lib/ 源文件对运行时零影响。实测佐证往lib/ffi/abi.dart注入语法错误dart运行完全无视——运行时吃的根本不是这个文件。判定口径只要症状是「改了源码、行为不变」先怀疑「运行时到底吃的是哪份代码」。对 Dart 来说答案是 JIT 内嵌的 platform kernel不是缓存目录里的 lib/。3.2 从源码构建四步走方案改为按 3.47.4 DEPS 锁定的 dart 版本1d1a730ef9 Dart 3.13.3从源码构建dart 版本不是自选的Flutter 仓库根部的DEPS文件锁定 dart revision本批次为1d1a730ef9即 Dart 3.13.3——必须检出 DEPS 锁定的版本自选一个「差不多」的版本会让 framework 与 Dart 的接口契约错位错误还会延迟到构建期才暴露。# 1) 检出 DEPS 锁定的 dart 版本关键布局.gclient 必须在父目录# checkout 目录名必须恰为 sdk# 2) gclient sync —— deps 落到 checkout 根buildtools、third_party、tools/sdks# 3) 应用三个 ohos ffi 补丁锚点以 3.12.2-ohos 参考实现为准# lib/ffi/abi.dart 公共 const values 列表 私有 const _OS 枚举加 ohos# lib/ffi/abi_specific.dart 文档表 3 行# lib/_internal/vm/lib/ffi_patch.dart 指针宽度表 3 行# 4) 构建注意--os macos 是非法参数默认 --os host → target_osmacpython3 tools/build.py--moderelease--archarm64 create_sdk# 产物xcodebuild/ReleaseARM64/dart-sdk两个容易翻车的细节目录名必须是sdkgclient 布局对 checkout 目录名敏感起别的名字 deps 落位全错--os macos不存在build.py 只认--os host映射target_osmac等少数值传 macos 直接报错。验证G2 门的一部分// verify_abi.dartimportdart:ffi;voidmain(){print([Abi.ohosArm,Abi.ohosArm64,Abi.ohosX64]);}$ dart --version Dart SDK version: 3.13.3 $ dart verify_abi.dart [ohos_arm, ohos_arm64, ohos_x64] ✅3.3 补丁集从 3 文件扩到 6 文件实测迭代的产物「三个 ffi 补丁就够」这个假设在构建 platform kernel 时被逐一击破——后三个补丁每个都是编译崩溃级才发现的。最终的 6 文件补丁集#文件内容不打的后果1lib/ffi/abi.dart公共 const ×3 values 列表 私有 const ×3 _OS枚举加 ohos运行时 ABI 缺失2lib/ffi/abi_specific.dart文档表 3 行同上3lib/_internal/vm/lib/ffi_patch.dart指针宽度表 3 行同上4lib/io/platform.dartstatic final bool isOhosPlatform.isOhos无法编译5lib/ffi/c_type.dart15 张表×Abi.ohosArm/ohosArm64/ohosX64 45 行运行时IntPtr表缺行——但编译期sizeOf仍过6pkg/vm/lib/modular/transformations/ffi/abi.dartVM 编译器侧 ABI 注册表镜像 Abi 类 _OS枚举 abiNamesmap nonSizeAlignment表Type IntPtr has no mapping for ABI (ohos, arm)/Null check operator used on a null valuegetAlignmentFor第 5、6 个补丁有两个工程细节值得记c_type.dart 用「位置对齐」方案打入ref参考实现减掉 ohos 行后必须与 stock逐行对齐才敢打其中 ref 562/604 两处androidX64 Uint32→Int32是上游 3.12→3.13 的官方改动保留 stock 值不动nonSizeAlignment按平台分组ohosArm与androidArm同组用 32Align64ohosArm64/X64用 64——对齐规则不能照抄 arm64。第 5 个补丁是「编译期过、运行时炸」的典型sizeOf编译期仍通过缺行只在运行时IntPtr查表时爆出来——补丁集完整性必须靠「构建 platform kernel 全绿」来判定不能靠编译过。补丁集与构建流程已固化为可重跑脚本scripts/patch_and_build_dart_ohos.sh本批次构建 104/104 通过产物xcodebuild/ReleaseARM64/dart-sdk——下一批次换 dart 版本时脚本是重放的第一入口。3.4 装机细节替换 dart-sdk但 engine.stamp 不动构建出的dart-sdk替换进 flutter SDK 的缓存目录两个动作必须成套做# 原版留备份出问题可秒回退mvbin/cache/dart-sdk bin/cache/dart-sdk-stock-3.13.3.bakcp-rxcodebuild/ReleaseARM64/dart-sdk bin/cache/dart-sdk# engine.stamp 保持不动仍等于 engine.version 06a2e2a1engine.stamp 为什么不能动flutter_tools 用 stamp 与engine.version的比对决定是否重新下载 engine 工件。替换 dart-sdk 与 engine 版本无关——动 stamp 会误触发 engine 重下把一个「Dart 层变更」放大成「引擎层变更」排查面瞬间扩大。⚠️ 上面这一套只解决了我这台 mac。--arch arm64编出来的二进制跨架构不可复用第 9 篇 §5.8 引的覆盖行注释原话是二进制全量重建所以适配 Dart在发布侧的真实成本是每个宿主平台各编一份macOS arm64、Windows x64 两份完整 Dart SDK外加 HAP 构建专用的dart-sdk-ohos运行时两份mac 的是 Mach-OWindows 的是 PE32不能互相替换。这是 Phase 4 的活儿本篇先把为什么非编不可讲透。3.5 第二个镜像sky_engine/lib 也要补flutter analyze分析 framework 时暴露了第二处隐藏镜像dart:io/dart:ffi的符号不从bin/cache/dart-sdk解析而从bin/cache/pkg/sky_engine/lib/解析——那是引擎发布包里 dart-sdk lib 的镜像 flutter patches。引擎 3.47.4 的镜像没有 ohos于是Platform.isOhos报 undefined与 3.2 节的 SDK 补丁是否打全无关。排查结论链供 Phase 3/4 参考.dart_tool/package_config.json里sky_engine → file:///…/bin/cache/pkg/sky_engine——确认解析路径该 pkg 的lib/io/platform.dart无isOhos——确认缺失把 6 个补丁文件 cp 过去即恢复另加 ui_web 枚举 stub 的ohos值forfinffi/abi.dart ffi/abi_specific.dart ffi/c_type.dart\_internal/vm/lib/ffi_patch.dart io/platform.dart;docpbin/cache/dart-sdk/lib/$fbin/cache/pkg/sky_engine/lib/$fdone这是分析期的临时手段。Phase 3 构建 ohos engine 发布包时必须让 sky_engine 自带补丁第 9 篇发布链路的一部分——临时 cp 只解决「这一台机器」。四、flutter_tools13 处 API 漂移的修复Dart SDK 就位后./bin/flutter --version触发的工具链编译爆出13 个错误——全部是 3.44.9 鸿蒙侧写法与 3.47.4 上游 API 的漂移。主要条目如下4.1 漂移修复清单#文件3.44.9 鸿蒙侧用法报错点3.47.4 对应物修复1ohos/hvigor_utils.dartimport ../reporting/reporting.dartreporting/ 目录已删仅剩 crash_reporting/compat删 import2同上BuildEvent(...).send()globals.logger.sendEvent(name, args)改写两行3build_info.dart旧版顶层getNameForTargetPlatform与新版 switch 版重复声明3way 合并把两个版本都留下了删旧 wrapper新 switch 版已含 ohos case4commands/clean.dartFuturevoid方法内return FlutterCommandResult3.47.4 把 run() 拆成_cleanProjectvoid删 return5commands/update_packages.dartwidgetPreviewScaffoldProject旧属 UpdatePackagesCommand移动为FlutterProject.widgetPreviewScaffoldProject加前缀rootProject.6build_system/targets/native_assets.dartohos 分支引用dartHookResult变量改名combinedResult改引用7build_system/targets/ohos.dartDartBuild.loadHookResult类改名LinkHooks改类名8同上依赖DartBuildForNative()类消失等价物LinkHooks()自带BuildHooks()依赖换依赖9artifacts.dart_getDartSdkPath调_getFlutterPrebuiltsPath(两参)类内 0 参方法去参10同上_getPrebuiltTarget(两参)同上去参11同上顶层_getPrebuiltTargetswitch 无 ohos case穷尽匹配失败补 4 个 ohos case归入 unsupported 组4.2 四类漂移模式13 处漂移归纳后只有四类下一批次可以直接按类排查改名/搬家#2、#5、#7、#8上游重构把类/方法挪位置——修法固定以上游新名为准改引用参数签名变化#9、#10方法从「带工具依赖参数」改成「0 参」——修法固定去参重复声明残留#3、#43way 合并的副产品——新旧两个版本都留在文件里删旧留新穷尽匹配缺口#1、#11上游删目录/改 switch——补 ohos case 或删 import。第 3 类最值得警惕它是「合并本身制造的问题」不是「上游改的问题」——三方重放后的编译错误先分清属于哪一类再动手。五、Phase 12 收官G1G2 双门通过5.1 收官状态落库提交bd061a09d6Phase 2 完成时的验收清单全部实测通过✅ 421 文件重打磁盘 0 冲突 14 个 unmerged 全部git add销账✅ Dart 3.13.3ohos 从源码构建并装机6 文件补丁集脚本已固化✅ flutter_tools 13 处 API 漂移修复工具编译通过版本横幅完整输出Flutter 3.47.4 · Dart 3.13.3ohos 定制✅flutter analyze全量 error 04 个 packages——G2 门通过_window_ohos.dart的 5 个WindowingOwneroverride 按 3.47.4 新签名重排size/constraints/resizableresizable暂为 no-opengine 未暴露TODO 已记录提交bd061a09d6提交标题Phase 2: re-apply OHOS adaptation to Flutter 3.47.4 framework (packages/)2026-09-13工作树仅剩pubspec.lock按约定不提交。pubspec.lock不提交是刻意的它记录了本地路径依赖2.2 节的解析结果各机器的本地 fork 位置不同锁文件必然机机不同——提交它只会制造无意义的协作 diff。5.2 遗留事项交棒 Phase 3/4 的三件事engine 源码获取engine revision06a2e2a1在上游 github 404需要找替代渠道——Phase 3 的第一个拦路虎sky_engine 镜像同步3.5 节的 cp 是分析期临时手段Phase 4 重建 engine 发布包时应让 sky_engine 自带补丁补丁脚本维护scripts/patch_and_build_dart_ohos.sh已固化下一批次换 dart 版本时以它为重放入口。六、Phase 12 复盘三条可迁移的教训抛开本项目细节这两个阶段沉淀了三条对任何「fork 上游同步」都成立的教训环境故障优先于一切本批次 95% 的「不可思议错误」最后都指向前置条件代理 HTTP/2、缓存镜像、stamp 状态——排查顺序永远是「环境 → 配置 → 代码」「干净」是最危险的表象磁盘 0 冲突 ≠ 合并完成编译过 ≠ 运行时对c_type 补丁、补丁打了 ≠ 生效platform kernel——每个「通过」后面都要问一句「它到底验证了什么」隐藏依赖会逐个暴露要按清单管理ffi 三件套 → isOhos → IntPtr 表 → VM 编译器 ABI 表 → sky_engine 镜像每个都是撞出来的——把每次撞出来的依赖当场写进补丁清单/文档是「下一批次变快」的唯一方式。七、常见问题 FAQ7.1 踩坑速查表域现象原因处理网络全量 clone 两次失败curl 18 / early EOF本地代理杀死 HTTP/2 大包git config --global http.version HTTP/1.1重放以为 3way 合并完成磁盘 0 冲突标记14 文件停留 unmerged 索引态git diff --diff-filterU逐个确认 git add重放工具链构建期才报 hooks API 错误pub 解析了上游 hooks 包pubspec 两处 path 依赖指本地 forkDart SDKAbi.ohosArmMember not founddart JIT 内嵌 platform kernel缓存补丁零影响从源码构建3.2 节Dart SDKgclient deps 落位全错.gclient必须在父目录、目录名必须恰为sdk按布局重做3.2 节Dart SDKbuild.py 参数报错--os macos是非法参数用默认--os host3.2 节Dart SDKIntPtr has no mapping for ABI补丁集不完整3 文件假设不成立6 文件补丁集3.3 节analyzePlatform.isOhosundefinedsky_engine/lib 第二镜像无 ohoscp 6 补丁文件 ui_web stub3.5 节缓存engine 工件被意外重下误改 engine.stampstamp 保持等于 engine.version3.4 节7.2 当前发布版是 3.47.8本文的 3.47.4 还有参考价值吗有。Phase 1 建基线、Phase 2 重放 framework 适配、Dart SDK 源码构建、sky_engine 第二镜像这四件事在 3.47.8 批次里同样要做只是坐标换成新的 tag/revision。照做时把四个坐标替换掉即可旧基线、上游目标 tag、分叉分支、engine / Dart revision验证门G1/G2不变。7.3 为什么 Dart SDK 必须从源码构建改缓存为什么无效因为 Dart JIT 把 platform kernel 内嵌进了产物bin/cache/dart-sdk里的二进制并不是唯一事实源只给缓存打补丁JIT 仍走内嵌的旧 kernel于是Abi.ohosArm在运行时才报 Member not found。正确路径是按 3.2 节从源码构建并把补丁集补全到 6 个文件3.3 节。7.4Platform.isOhosundefined 是怎么回事framework 的flutter analyze依赖两份 sky_engine一份在 engine 产物里一份在sky_engine/lib镜像里。只补前者后者仍没有 ohos 平台定义analyze 就会报未定义。处理是把 6 个补丁文件同步进第二镜像并补上ui_webstub3.5 节而不是在业务代码里加忽略。7.5 有代理时 clone 总是断怎么办先强制 HTTP/1.1再浅克隆单分支git config --global http.version HTTP/1.1然后git clone --depth 1 --single-branch --branch branch ...。不要用「重试到成功」掩盖问题——同一代理下大包传输每次都会断在相近位置。代理端口按本机实际配置调整。7.6 复现 Phase 12 需要什么环境Flutter OH 基线3.44.9当前发布版3.47.8-ohos-1.0.0、上游目标3.47.4DevEco Studio 26.0.0 ReleaseOpenHarmony SDK / API 26macOS arm64、≥88GB 空闲磁盘、git / python3 / clang / ninja / node。环境变量与工具链配置见官方环境搭建指导。八、系列导航「鸿蒙Flutter框架 0day适配实战」全系列 10 篇本篇为第 6 篇生产侧 Phase 12#篇目侧一句话主题01背景、分叉仓库、版本命名与 fvm fork 安装消费三层架构、三个接缝、七层工作量、fvm 直装 tag、版本墙02tag 版本的手动安装与三层核验消费浅克隆 bootstrap、首次初始化、SSH 修复、异常分诊03鸿蒙模拟器/真机跑 Flutter 消费侧踩坑集消费工具链三件套、HAP 构建/安装/运行、占位签名、截图取证、CP1-CP1404flutter build hap 自动签名消费P12/CSR、AGC 证书与 Profile、纯 Dart AES-GCM、C0-C10 复用05上游同步总览、BC 全景与端到端 SOP生产批次解剖、五阶段验证门、12 项适配表、端到端 SOP 与 P1-P29 索引06Phase 12基线建立与 Framework 适配本篇生产代理 HTTP/1.1 修障、421 文件重打、Dart SDK 源码构建07Phase 3 Engine三方重放与冲突裁决生产826 文件、15 真冲突两分法、契约对齐 16 项08引擎构建链攻防生产依赖树、工具链版本、链接与测试面 27 坑09构建发布与产物分发生产版本锁、11 个工件Dart SDK 双宿主、11 条覆盖键、换新 tag 铁律10验证与真机验收生产三档引擎、设备侧单测、字体图标静默故障配套仓库与文档鸿蒙分叉仓库当前主线 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter上游 Flutter 仓库github.com/flutter/flutterDart SDK 源码3.2 节构建对象github.com/dart-lang/sdk本地 fork 的 dart native 包2.2 节路径依赖atomgit.com/hxa-flutter/fluttertpc_dart_nativeFlutter OH 环境搭建指导OpenHarmony-flutter 环境搭建指导Flutter 官方文档docs.flutter.devDart 官方文档dart.dev总结本篇走完了同步流水线的地基Phase 1 用一行git config http.version HTTP/1.1修掉代理杀 HTTP/2 大包的网络坑浅克隆建基线、拉两个上游 tag、git diff --name-status恢复并校验 2263 文件权威清单G1 门Phase 2 用git apply --3way重打 421 个 packages 文件0 冲突标记但 14 个 unmerged 要逐个销账撞出了本阶段最大发现——Dart SDK 不能打缓存补丁JIT 内嵌 platform kernel必须从源码构建补丁集从 3 文件迭代到 6 文件sky_engine/lib 还有第二镜像要同步最后 flutter_tools 13 处 API 漂移修复、flutter analyze全量 0 errorG2 门收官于 commitbd061a09d6。三条复盘教训环境优先、「干净」最危险、隐藏依赖按清单管理对任何 fork 同步都成立。下一篇第 7 篇进入 Phase 3——全批次工作量最高的 engine 侧826 文件重打、15 个真冲突的两分法裁决以及契约对齐 16 项G3 门。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源Flutter OH 环境搭建指导OpenHarmony-flutter 环境搭建指导分叉仓库3.47 线当前发布 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter上游 Flutter 仓库github.com/flutter/flutterDart SDK 源码github.com/dart-lang/sdk本地 fork 的 dart native 包atomgit.com/hxa-flutter/fluttertpc_dart_nativeFlutter 官方文档docs.flutter.devDart 官方文档dart.dev开源鸿蒙跨平台社区openharmonycrossplatform.csdn.net环境与版本本文的示例与截图基于以下环境组合2026-10 实测组件版本说明上游 Flutter SDK3.47.8github.com/flutter/flutterFlutter SDKOH 适配版3.47.8-ohos-1.0.0oh-flutter/flutter_flutteroh-3.47-dev分支DevEco Studio26.0.0 Release提供 hvigor / ohpm / hdc / JBR 等工具链OpenHarmony SDK / APIAPI 2626.0.0模拟器与 SDK 均为 API 26运行设备OpenHarmony 模拟器API 261280×2832环境搭建分叉获取、DevEco Studio 与 SDK 配置、模拟器创建请按官方指导操作OpenHarmony-flutter 环境搭建指导。本文正文是 2026-093.44.9 → 3.47.4同步批次的实录其中的版本号、提交号与实测数字适配清单文件数、构建边数、单测用例数、工件字节数等都是那一批的现场值不随上表更新上表是当前可复现、可照做的环境组合。方法论、验证门与坑模型对 3.47.8 线同样适用。 
长河君 · 2026/10/30 6:52:22 · 阅读 1.2k 鸿蒙Flutter框架 0day适配实战：06 同步 Phase 1+2：基线建立与 Framework 适配，附「Dart SDK 必须从源码构建」
前言版本口径2026-10当前正式发布版为Flutter OH 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter配套DevEco Studio 26.0.0 Release与OpenHarmony SDK / API 26。本篇是 2026-093.44.9 → 3.47.4批次的 Phase 12 实录命令与验证方法对 3.47.8 线同样适用。环境搭建见Flutter OH 环境搭建指导。第 5 篇给了生产侧的总图全新分支 三方重放不 merge五阶段、五道验证门。本篇放大Phase 1基线建立与 Phase 2Framework 适配两个阶段的实操细节——它们是整条流水线的地基也是本批次踩坑最「前置」的两个阶段Phase 1 的最大坑本地代理杀死 HTTP/2 大包传输全量 clone 两次失败一行git config解决Phase 2 的最大发现Dart SDK 必须从源码构建——给缓存目录里的 dart-sdk 打补丁是「零影响」的假动作补丁集也从 3 文件迭代到 6 文件。这两段内容对任何要做「上游同步」的分叉维护者都是通用经验不依赖本项目的具体版本号。全部操作取自 2026-09-13 批次实录macOS 15.4.1 arm64 新机。前置阅读第 5 篇的基线表四个坐标与清单概念。本篇从「四个坐标已核验」开始。一、Phase 1基线建立G1 门1.1 网络修障在前代理杀死 HTTP/2 大包基线建立的第一步不是 clone而是修网络。全量 clone 连续两次失败报错签名curl 18: transfer closed with outstanding read data remaining error: RPC failed; curl 56 fatal: early EOF小请求全部正常只有大包传输断裂——根因是本地代理127.0.0.1:1087杀死 HTTP/2 大包传输。修法是强制 git 走 HTTP/1.1gitconfig--globalhttp.version HTTP/1.1修复后 shallow clone 与 github 大包 fetch 全部一次通过。建议只要本机有 HTTP 代理就把http.versionHTTP/1.1设为永续全局配置——这是本批次「最前置」的坑不修它后面每一步都在重复失败。1.2 浅克隆分叉仓库 挂 upstream remotegit-chttp.versionHTTP/1.1 clone--depth1--single-branch\--branchoh-3.44.9-dev https://atomgit.com/oh-flutter/flutter_flutter.gitcdflutter_fluttergitremoteaddupstream https://github.com/flutter/flutter.git三个决策点--depth 1 --single-branch只取oh-3.44.9-dev的 tip17400 文件工作树 235MB / .git 42MB——全新分支方案不需要鸿蒙侧历史树级 diff 不受影响挂upstreamremote后续所有上游 tag 都从它 fetch不碰 origin 的引用空间HEAD 核验clone 完先对 HEAD本批次fe316cf7✅与旧机调研一致再往下走。1.3 拉取上游两个 taggitfetch--depth1upstream\refs/tags/3.47.4:refs/tags/3.47.4\refs/tags/3.44.9:refs/tags/3.44.9拉下来对 SHA第 5 篇 2.1 节基线表3.47.49584c6713b324636289d067944a46fd6b49df14b✅3.44.96b182d2c7585eba26d4edce0f97630effd256c33✅两个 tag 的用途不同3.47.4是新基线第 1.4 节3.44.9是适配清单的 diff 起点第 1.5 节——两个都缺一个Phase 1 就不算完成。1.4 创建基线分支gitcheckout-boh-3.47.4-dev3.47.4# HEAD 9584c671 ✅分支命名沿用oh-上游版本-dev风格release 分支在发布时切。此后这个分支上的一切改动都是「适配重放」的产物不混入任何 merge——第 5 篇 2.3 节三条理由在这里开始兑现。1.5 适配清单恢复与校验用「上游旧基线 ↔ 鸿蒙旧分支」的树级 diff 恢复适配清单gitdiff--name-status3.44.9 oh-3.44.9-devsync-data/ohos_adapt_list.txtwc-lsync-data/ohos_adapt_list.txt校验结果与旧机调研值逐项对账指标旧机调研值新机实测结论总文件22632263✅新增 A / 修改 M / 删除 D1738 / 522 / 31738 / 522 / 3✅行 / -行192740192740 / -2018✅顶层分布—engine 826 · dev 633 · packages 421 · examples 265 · ci 41 · 其他 ~80新增G1 验证门通过旧机全部研究数据在新机可复现sync-data/ohos_adapt_list.txt成为整批次的权威清单第 5 篇 3.6 节讲的三个读法都作用在这个文件上。浅克隆 树级 diff 是无损的——2263 文件清单一个不少。后续如需鸿蒙侧历史git log/blame写文档再git fetch --unshallow origin代价 GB 级 时间不必提前付。1.6 Phase 1 验收卡把 Phase 1 的五个动作与验收判据收进一张卡过这张卡G1 门才算数步骤动作验收判据1网络修障HTTP/1.1一次fetch --depth 1大包成功2浅克隆 挂 upstream工作树 235MB / .git 42MBHEAD 对账 ✅3fetch 两个上游 tagSHA 与基线表逐项一致 ✅4checkout -b oh-3.47.4-dev分支 HEAD 3.47.4tag 的 SHA5树级 diff 恢复清单2263 文件 / A-M-D / 行数 四项与旧机调研值全对上G1 门的本质让「清单」先于「重放」成为权威。清单不校验就开重放等于在没有地图的地方开车——错一行Phase 2/3 全跟着错。二、Phase 2Framework 适配421 文件三方重打2.1 git apply --3way0 冲突标记但别信「干净」从清单里圈出 packages/ 工作集421 文件以新基线为三方基准重放# 从权威清单圈出 Phase 2 工作集排除删除项awk$1 ! D(grep-E^[AMD].*packages/sync-data/ohos_adapt_list.txt|awk{print $3})# 以基线版本为三方基准三方合并gitapply--3waypackages 子集 diff重放后的真实状态有两层只看第一层会误判磁盘上0 个冲突标记没有——看起来「干净」但14 个文件停留在 unmerged 索引态——内容已经正确git 只是没确认# 找出停在 unmerged 态的文件gitdiff--diff-filterU --name-only# 内容正确直接确认gitadd上述文件「磁盘 0 冲突」≠「合并完成」。git apply --3way的 3-way 结果可能把冲突静默解决后留在索引里必须用git diff --diff-filterU逐个确认——「以为合完了」是三方重放的第一大假象。2.2 pubspec两处路径依赖改指本地 fork重打完还要处理flutter_tools/pubspec.yaml的两处路径依赖code_assets与hooks_runner改指本地 forkfluttertpc_dart_native/pkgs/保证 dart native hooks 的 ohos 支持与 3.47.4 的 hooks 1.5.0 API 一致dependencies:code_assets:path:../fluttertpc_dart_native/pkgs/code_assets# 本地 forkhooks_runner:path:../fluttertpc_dart_native/pkgs/hooks_runner# 本地 fork这一步不做的后果pub 会解析上游版本的 hooks 包与 3.47.4 的 API 对不上工具链在构建期才炸——比编译期报错晚一个阶段排查成本翻倍。三、本阶段最大发现Dart SDK 必须从源码构建Phase 2 真正的硬骨头不在 421 文件而在工具链的隐藏依赖定制 Dart SDK 不能「打补丁」必须从源码构建。本节是这个发现的完整链条也是最值得生产侧读者精读的部分。上图就是本节的全景上半是「正确路径」五步clone Dart 源码 → 6 文件补丁集 → 构建 patched_sdk → framework 用它编译 → sky_engine/lib 同步与验收判据左下是「错误路径」的三连击改缓存 dart-sdk 零影响 → JIT 内嵌 platform kernel → 症状不变右下是 421 文件三方重放的冲突形态0 冲突标记但 14 个 unmerged。底部结论一句话Dart 层是「源码构建」问题不是「改缓存文件」问题补丁集要 6 个文件不是 3 个。3.1 「打补丁缓存」为什么是零影响现象把 3.12.2-ohos SDK 的三个 ffi 补丁abi.dart、abi_specific.dart、ffi_patch.dart打到官方 3.13.3 的bin/cache/dart-sdk上然后验证import dart:ffi; print(Abi.ohosArm); // Member not found: Abi.ohosArm还是Member not found——补丁「打了个寂寞」。根因dartJIT 二进制内嵌了 platform kernel——lib/ffi、lib/_internal/vm/lib/ffi_patch.dart等源文件在构建期就编译进了 vm_platform 固件。改 SDK 仓库里的 lib/ 源文件对运行时零影响。实测佐证往lib/ffi/abi.dart注入语法错误dart运行完全无视——运行时吃的根本不是这个文件。判定口径只要症状是「改了源码、行为不变」先怀疑「运行时到底吃的是哪份代码」。对 Dart 来说答案是 JIT 内嵌的 platform kernel不是缓存目录里的 lib/。3.2 从源码构建四步走方案改为按 3.47.4 DEPS 锁定的 dart 版本1d1a730ef9 Dart 3.13.3从源码构建dart 版本不是自选的Flutter 仓库根部的DEPS文件锁定 dart revision本批次为1d1a730ef9即 Dart 3.13.3——必须检出 DEPS 锁定的版本自选一个「差不多」的版本会让 framework 与 Dart 的接口契约错位错误还会延迟到构建期才暴露。# 1) 检出 DEPS 锁定的 dart 版本关键布局.gclient 必须在父目录# checkout 目录名必须恰为 sdk# 2) gclient sync —— deps 落到 checkout 根buildtools、third_party、tools/sdks# 3) 应用三个 ohos ffi 补丁锚点以 3.12.2-ohos 参考实现为准# lib/ffi/abi.dart 公共 const values 列表 私有 const _OS 枚举加 ohos# lib/ffi/abi_specific.dart 文档表 3 行# lib/_internal/vm/lib/ffi_patch.dart 指针宽度表 3 行# 4) 构建注意--os macos 是非法参数默认 --os host → target_osmacpython3 tools/build.py--moderelease--archarm64 create_sdk# 产物xcodebuild/ReleaseARM64/dart-sdk两个容易翻车的细节目录名必须是sdkgclient 布局对 checkout 目录名敏感起别的名字 deps 落位全错--os macos不存在build.py 只认--os host映射target_osmac等少数值传 macos 直接报错。验证G2 门的一部分// verify_abi.dartimportdart:ffi;voidmain(){print([Abi.ohosArm,Abi.ohosArm64,Abi.ohosX64]);}$ dart --version Dart SDK version: 3.13.3 $ dart verify_abi.dart [ohos_arm, ohos_arm64, ohos_x64] ✅3.3 补丁集从 3 文件扩到 6 文件实测迭代的产物「三个 ffi 补丁就够」这个假设在构建 platform kernel 时被逐一击破——后三个补丁每个都是编译崩溃级才发现的。最终的 6 文件补丁集#文件内容不打的后果1lib/ffi/abi.dart公共 const ×3 values 列表 私有 const ×3 _OS枚举加 ohos运行时 ABI 缺失2lib/ffi/abi_specific.dart文档表 3 行同上3lib/_internal/vm/lib/ffi_patch.dart指针宽度表 3 行同上4lib/io/platform.dartstatic final bool isOhosPlatform.isOhos无法编译5lib/ffi/c_type.dart15 张表×Abi.ohosArm/ohosArm64/ohosX64 45 行运行时IntPtr表缺行——但编译期sizeOf仍过6pkg/vm/lib/modular/transformations/ffi/abi.dartVM 编译器侧 ABI 注册表镜像 Abi 类 _OS枚举 abiNamesmap nonSizeAlignment表Type IntPtr has no mapping for ABI (ohos, arm)/Null check operator used on a null valuegetAlignmentFor第 5、6 个补丁有两个工程细节值得记c_type.dart 用「位置对齐」方案打入ref参考实现减掉 ohos 行后必须与 stock逐行对齐才敢打其中 ref 562/604 两处androidX64 Uint32→Int32是上游 3.12→3.13 的官方改动保留 stock 值不动nonSizeAlignment按平台分组ohosArm与androidArm同组用 32Align64ohosArm64/X64用 64——对齐规则不能照抄 arm64。第 5 个补丁是「编译期过、运行时炸」的典型sizeOf编译期仍通过缺行只在运行时IntPtr查表时爆出来——补丁集完整性必须靠「构建 platform kernel 全绿」来判定不能靠编译过。补丁集与构建流程已固化为可重跑脚本scripts/patch_and_build_dart_ohos.sh本批次构建 104/104 通过产物xcodebuild/ReleaseARM64/dart-sdk——下一批次换 dart 版本时脚本是重放的第一入口。3.4 装机细节替换 dart-sdk但 engine.stamp 不动构建出的dart-sdk替换进 flutter SDK 的缓存目录两个动作必须成套做# 原版留备份出问题可秒回退mvbin/cache/dart-sdk bin/cache/dart-sdk-stock-3.13.3.bakcp-rxcodebuild/ReleaseARM64/dart-sdk bin/cache/dart-sdk# engine.stamp 保持不动仍等于 engine.version 06a2e2a1engine.stamp 为什么不能动flutter_tools 用 stamp 与engine.version的比对决定是否重新下载 engine 工件。替换 dart-sdk 与 engine 版本无关——动 stamp 会误触发 engine 重下把一个「Dart 层变更」放大成「引擎层变更」排查面瞬间扩大。⚠️ 上面这一套只解决了我这台 mac。--arch arm64编出来的二进制跨架构不可复用第 9 篇 §5.8 引的覆盖行注释原话是二进制全量重建所以适配 Dart在发布侧的真实成本是每个宿主平台各编一份macOS arm64、Windows x64 两份完整 Dart SDK外加 HAP 构建专用的dart-sdk-ohos运行时两份mac 的是 Mach-OWindows 的是 PE32不能互相替换。这是 Phase 4 的活儿本篇先把为什么非编不可讲透。3.5 第二个镜像sky_engine/lib 也要补flutter analyze分析 framework 时暴露了第二处隐藏镜像dart:io/dart:ffi的符号不从bin/cache/dart-sdk解析而从bin/cache/pkg/sky_engine/lib/解析——那是引擎发布包里 dart-sdk lib 的镜像 flutter patches。引擎 3.47.4 的镜像没有 ohos于是Platform.isOhos报 undefined与 3.2 节的 SDK 补丁是否打全无关。排查结论链供 Phase 3/4 参考.dart_tool/package_config.json里sky_engine → file:///…/bin/cache/pkg/sky_engine——确认解析路径该 pkg 的lib/io/platform.dart无isOhos——确认缺失把 6 个补丁文件 cp 过去即恢复另加 ui_web 枚举 stub 的ohos值forfinffi/abi.dart ffi/abi_specific.dart ffi/c_type.dart\_internal/vm/lib/ffi_patch.dart io/platform.dart;docpbin/cache/dart-sdk/lib/$fbin/cache/pkg/sky_engine/lib/$fdone这是分析期的临时手段。Phase 3 构建 ohos engine 发布包时必须让 sky_engine 自带补丁第 9 篇发布链路的一部分——临时 cp 只解决「这一台机器」。四、flutter_tools13 处 API 漂移的修复Dart SDK 就位后./bin/flutter --version触发的工具链编译爆出13 个错误——全部是 3.44.9 鸿蒙侧写法与 3.47.4 上游 API 的漂移。主要条目如下4.1 漂移修复清单#文件3.44.9 鸿蒙侧用法报错点3.47.4 对应物修复1ohos/hvigor_utils.dartimport ../reporting/reporting.dartreporting/ 目录已删仅剩 crash_reporting/compat删 import2同上BuildEvent(...).send()globals.logger.sendEvent(name, args)改写两行3build_info.dart旧版顶层getNameForTargetPlatform与新版 switch 版重复声明3way 合并把两个版本都留下了删旧 wrapper新 switch 版已含 ohos case4commands/clean.dartFuturevoid方法内return FlutterCommandResult3.47.4 把 run() 拆成_cleanProjectvoid删 return5commands/update_packages.dartwidgetPreviewScaffoldProject旧属 UpdatePackagesCommand移动为FlutterProject.widgetPreviewScaffoldProject加前缀rootProject.6build_system/targets/native_assets.dartohos 分支引用dartHookResult变量改名combinedResult改引用7build_system/targets/ohos.dartDartBuild.loadHookResult类改名LinkHooks改类名8同上依赖DartBuildForNative()类消失等价物LinkHooks()自带BuildHooks()依赖换依赖9artifacts.dart_getDartSdkPath调_getFlutterPrebuiltsPath(两参)类内 0 参方法去参10同上_getPrebuiltTarget(两参)同上去参11同上顶层_getPrebuiltTargetswitch 无 ohos case穷尽匹配失败补 4 个 ohos case归入 unsupported 组4.2 四类漂移模式13 处漂移归纳后只有四类下一批次可以直接按类排查改名/搬家#2、#5、#7、#8上游重构把类/方法挪位置——修法固定以上游新名为准改引用参数签名变化#9、#10方法从「带工具依赖参数」改成「0 参」——修法固定去参重复声明残留#3、#43way 合并的副产品——新旧两个版本都留在文件里删旧留新穷尽匹配缺口#1、#11上游删目录/改 switch——补 ohos case 或删 import。第 3 类最值得警惕它是「合并本身制造的问题」不是「上游改的问题」——三方重放后的编译错误先分清属于哪一类再动手。五、Phase 12 收官G1G2 双门通过5.1 收官状态落库提交bd061a09d6Phase 2 完成时的验收清单全部实测通过✅ 421 文件重打磁盘 0 冲突 14 个 unmerged 全部git add销账✅ Dart 3.13.3ohos 从源码构建并装机6 文件补丁集脚本已固化✅ flutter_tools 13 处 API 漂移修复工具编译通过版本横幅完整输出Flutter 3.47.4 · Dart 3.13.3ohos 定制✅flutter analyze全量 error 04 个 packages——G2 门通过_window_ohos.dart的 5 个WindowingOwneroverride 按 3.47.4 新签名重排size/constraints/resizableresizable暂为 no-opengine 未暴露TODO 已记录提交bd061a09d6提交标题Phase 2: re-apply OHOS adaptation to Flutter 3.47.4 framework (packages/)2026-09-13工作树仅剩pubspec.lock按约定不提交。pubspec.lock不提交是刻意的它记录了本地路径依赖2.2 节的解析结果各机器的本地 fork 位置不同锁文件必然机机不同——提交它只会制造无意义的协作 diff。5.2 遗留事项交棒 Phase 3/4 的三件事engine 源码获取engine revision06a2e2a1在上游 github 404需要找替代渠道——Phase 3 的第一个拦路虎sky_engine 镜像同步3.5 节的 cp 是分析期临时手段Phase 4 重建 engine 发布包时应让 sky_engine 自带补丁补丁脚本维护scripts/patch_and_build_dart_ohos.sh已固化下一批次换 dart 版本时以它为重放入口。六、Phase 12 复盘三条可迁移的教训抛开本项目细节这两个阶段沉淀了三条对任何「fork 上游同步」都成立的教训环境故障优先于一切本批次 95% 的「不可思议错误」最后都指向前置条件代理 HTTP/2、缓存镜像、stamp 状态——排查顺序永远是「环境 → 配置 → 代码」「干净」是最危险的表象磁盘 0 冲突 ≠ 合并完成编译过 ≠ 运行时对c_type 补丁、补丁打了 ≠ 生效platform kernel——每个「通过」后面都要问一句「它到底验证了什么」隐藏依赖会逐个暴露要按清单管理ffi 三件套 → isOhos → IntPtr 表 → VM 编译器 ABI 表 → sky_engine 镜像每个都是撞出来的——把每次撞出来的依赖当场写进补丁清单/文档是「下一批次变快」的唯一方式。七、常见问题 FAQ7.1 踩坑速查表域现象原因处理网络全量 clone 两次失败curl 18 / early EOF本地代理杀死 HTTP/2 大包git config --global http.version HTTP/1.1重放以为 3way 合并完成磁盘 0 冲突标记14 文件停留 unmerged 索引态git diff --diff-filterU逐个确认 git add重放工具链构建期才报 hooks API 错误pub 解析了上游 hooks 包pubspec 两处 path 依赖指本地 forkDart SDKAbi.ohosArmMember not founddart JIT 内嵌 platform kernel缓存补丁零影响从源码构建3.2 节Dart SDKgclient deps 落位全错.gclient必须在父目录、目录名必须恰为sdk按布局重做3.2 节Dart SDKbuild.py 参数报错--os macos是非法参数用默认--os host3.2 节Dart SDKIntPtr has no mapping for ABI补丁集不完整3 文件假设不成立6 文件补丁集3.3 节analyzePlatform.isOhosundefinedsky_engine/lib 第二镜像无 ohoscp 6 补丁文件 ui_web stub3.5 节缓存engine 工件被意外重下误改 engine.stampstamp 保持等于 engine.version3.4 节7.2 当前发布版是 3.47.8本文的 3.47.4 还有参考价值吗有。Phase 1 建基线、Phase 2 重放 framework 适配、Dart SDK 源码构建、sky_engine 第二镜像这四件事在 3.47.8 批次里同样要做只是坐标换成新的 tag/revision。照做时把四个坐标替换掉即可旧基线、上游目标 tag、分叉分支、engine / Dart revision验证门G1/G2不变。7.3 为什么 Dart SDK 必须从源码构建改缓存为什么无效因为 Dart JIT 把 platform kernel 内嵌进了产物bin/cache/dart-sdk里的二进制并不是唯一事实源只给缓存打补丁JIT 仍走内嵌的旧 kernel于是Abi.ohosArm在运行时才报 Member not found。正确路径是按 3.2 节从源码构建并把补丁集补全到 6 个文件3.3 节。7.4Platform.isOhosundefined 是怎么回事framework 的flutter analyze依赖两份 sky_engine一份在 engine 产物里一份在sky_engine/lib镜像里。只补前者后者仍没有 ohos 平台定义analyze 就会报未定义。处理是把 6 个补丁文件同步进第二镜像并补上ui_webstub3.5 节而不是在业务代码里加忽略。7.5 有代理时 clone 总是断怎么办先强制 HTTP/1.1再浅克隆单分支git config --global http.version HTTP/1.1然后git clone --depth 1 --single-branch --branch branch ...。不要用「重试到成功」掩盖问题——同一代理下大包传输每次都会断在相近位置。代理端口按本机实际配置调整。7.6 复现 Phase 12 需要什么环境Flutter OH 基线3.44.9当前发布版3.47.8-ohos-1.0.0、上游目标3.47.4DevEco Studio 26.0.0 ReleaseOpenHarmony SDK / API 26macOS arm64、≥88GB 空闲磁盘、git / python3 / clang / ninja / node。环境变量与工具链配置见官方环境搭建指导。八、系列导航「鸿蒙Flutter框架 0day适配实战」全系列 10 篇本篇为第 6 篇生产侧 Phase 12#篇目侧一句话主题01背景、分叉仓库、版本命名与 fvm fork 安装消费三层架构、三个接缝、七层工作量、fvm 直装 tag、版本墙02tag 版本的手动安装与三层核验消费浅克隆 bootstrap、首次初始化、SSH 修复、异常分诊03鸿蒙模拟器/真机跑 Flutter 消费侧踩坑集消费工具链三件套、HAP 构建/安装/运行、占位签名、截图取证、CP1-CP1404flutter build hap 自动签名消费P12/CSR、AGC 证书与 Profile、纯 Dart AES-GCM、C0-C10 复用05上游同步总览、BC 全景与端到端 SOP生产批次解剖、五阶段验证门、12 项适配表、端到端 SOP 与 P1-P29 索引06Phase 12基线建立与 Framework 适配本篇生产代理 HTTP/1.1 修障、421 文件重打、Dart SDK 源码构建07Phase 3 Engine三方重放与冲突裁决生产826 文件、15 真冲突两分法、契约对齐 16 项08引擎构建链攻防生产依赖树、工具链版本、链接与测试面 27 坑09构建发布与产物分发生产版本锁、11 个工件Dart SDK 双宿主、11 条覆盖键、换新 tag 铁律10验证与真机验收生产三档引擎、设备侧单测、字体图标静默故障配套仓库与文档鸿蒙分叉仓库当前主线 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter上游 Flutter 仓库github.com/flutter/flutterDart SDK 源码3.2 节构建对象github.com/dart-lang/sdk本地 fork 的 dart native 包2.2 节路径依赖atomgit.com/hxa-flutter/fluttertpc_dart_nativeFlutter OH 环境搭建指导OpenHarmony-flutter 环境搭建指导Flutter 官方文档docs.flutter.devDart 官方文档dart.dev总结本篇走完了同步流水线的地基Phase 1 用一行git config http.version HTTP/1.1修掉代理杀 HTTP/2 大包的网络坑浅克隆建基线、拉两个上游 tag、git diff --name-status恢复并校验 2263 文件权威清单G1 门Phase 2 用git apply --3way重打 421 个 packages 文件0 冲突标记但 14 个 unmerged 要逐个销账撞出了本阶段最大发现——Dart SDK 不能打缓存补丁JIT 内嵌 platform kernel必须从源码构建补丁集从 3 文件迭代到 6 文件sky_engine/lib 还有第二镜像要同步最后 flutter_tools 13 处 API 漂移修复、flutter analyze全量 0 errorG2 门收官于 commitbd061a09d6。三条复盘教训环境优先、「干净」最危险、隐藏依赖按清单管理对任何 fork 同步都成立。下一篇第 7 篇进入 Phase 3——全批次工作量最高的 engine 侧826 文件重打、15 个真冲突的两分法裁决以及契约对齐 16 项G3 门。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源Flutter OH 环境搭建指导OpenHarmony-flutter 环境搭建指导分叉仓库3.47 线当前发布 3.47.8-ohos-1.0.0atomgit.com/oh-flutter/flutter_flutter上游 Flutter 仓库github.com/flutter/flutterDart SDK 源码github.com/dart-lang/sdk本地 fork 的 dart native 包atomgit.com/hxa-flutter/fluttertpc_dart_nativeFlutter 官方文档docs.flutter.devDart 官方文档dart.dev开源鸿蒙跨平台社区openharmonycrossplatform.csdn.net环境与版本本文的示例与截图基于以下环境组合2026-10 实测组件版本说明上游 Flutter SDK3.47.8github.com/flutter/flutterFlutter SDKOH 适配版3.47.8-ohos-1.0.0oh-flutter/flutter_flutteroh-3.47-dev分支DevEco Studio26.0.0 Release提供 hvigor / ohpm / hdc / JBR 等工具链OpenHarmony SDK / APIAPI 2626.0.0模拟器与 SDK 均为 API 26运行设备OpenHarmony 模拟器API 261280×2832环境搭建分叉获取、DevEco Studio 与 SDK 配置、模拟器创建请按官方指导操作OpenHarmony-flutter 环境搭建指导。本文正文是 2026-093.44.9 → 3.47.4同步批次的实录其中的版本号、提交号与实测数字适配清单文件数、构建边数、单测用例数、工件字节数等都是那一批的现场值不随上表更新上表是当前可复现、可照做的环境组合。方法论、验证门与坑模型对 3.47.8 线同样适用。