前言

版本口径（2026-10）：当前正式发布版为 Flutter OH 3.47.8-ohos-1.0.0（atomgit.com/oh-flutter/flutter_flutter），配套 DevEco Studio 26.0.0 Release 与 OpenHarmony SDK / API 26。本篇是 2026-09 3.44.9 → 3.47.4 批次的 Phase 1+2 实录，命令与验证方法对 3.47.8 线同样适用。环境搭建见Flutter OH 环境搭建指导。

第 5 篇给了生产侧的总图：全新分支 + 三方重放（不 merge），五阶段、五道验证门。本篇放大 Phase 1（基线建立）与 Phase 2（Framework 适配） 两个阶段的实操细节——它们是整条流水线的地基，也是本批次踩坑最「前置」的两个阶段：

• 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.1：

git config --global http.version HTTP/1.1

修复后 shallow clone 与 github 大包 fetch 全部一次通过。

建议：只要本机有 HTTP 代理，就把 http.version=HTTP/1.1 设为永续全局配置——
这是本批次「最前置」的坑，不修它，后面每一步都在重复失败。

1.2 浅克隆分叉仓库 + 挂 upstream remote

git -c http.version=HTTP/1.1 clone --depth 1 --single-branch \
    --branch oh-3.44.9-dev https://atomgit.com/oh-flutter/flutter_flutter.git
cd flutter_flutter
git remote add upstream https://github.com/flutter/flutter.git

三个决策点：

1. --depth 1 --single-branch：只取 oh-3.44.9-dev 的 tip（17400 文件，工作树 235MB / .git 42MB）——全新分支方案不需要鸿蒙侧历史，树级 diff 不受影响；
2. 挂 upstream remote：后续所有上游 tag 都从它 fetch，不碰 origin 的引用空间；
3. HEAD 核验：clone 完先对 HEAD（本批次 fe316cf7 ✅，与旧机调研一致），再往下走。

1.3 拉取上游两个 tag

git fetch --depth 1 upstream \
  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.4 = 9584c6713b324636289d067944a46fd6b49df14b ✅
• 3.44.9 = 6b182d2c7585eba26d4edce0f97630effd256c33 ✅

两个 tag 的用途不同：3.47.4 是新基线（第 1.4 节），3.44.9 是适配清单的 diff 起点（第 1.5 节）——两个都缺一个，Phase 1 就不算完成。

1.4 创建基线分支

git checkout -b oh-3.47.4-dev 3.47.4
# HEAD = 9584c671 ✅

分支命名沿用 oh-<上游版本>-dev 风格（release 分支在发布时切）。此后这个分支上的一切改动都是「适配重放」的产物，不混入任何 merge——第 5 篇 2.3 节三条理由在这里开始兑现。

1.5 适配清单恢复与校验

用「上游旧基线 ↔ 鸿蒙旧分支」的树级 diff 恢复适配清单：

git diff --name-status 3.44.9 oh-3.44.9-dev > sync-data/ohos_adapt_list.txt
wc -l sync-data/ohos_adapt_list.txt

校验结果（与旧机调研值逐项对账）：

指标	旧机调研值	新机实测	结论
总文件	2263	2263	✅
新增 A / 修改 M / 删除 D	1738 / 522 / 3	1738 / 522 / 3	✅
+行 / -行	+192740	+192740 / -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 42MB；HEAD 对账 ✅
3	fetch 两个上游 tag	SHA 与基线表逐项一致 ✅
4	checkout -b oh-3.47.4-dev	分支 HEAD = 3.47.4 tag 的 SHA
5	树级 diff 恢复清单	2263 文件 / A-M-D / +行数 四项与旧机调研值全对上

G1 门的本质：让「清单」先于「重放」成为权威。
清单不校验就开重放，等于在没有地图的地方开车——错一行，Phase 2/3 全跟着错。

二、Phase 2：Framework 适配（421 文件三方重打）

2.1 git apply --3way：0 冲突标记，但别信「干净」

从清单里圈出 packages/ 工作集（421 文件），以新基线为三方基准重放：

# 从权威清单圈出 Phase 2 工作集（排除删除项）
awk '$1 != "D"' <(grep -E '^[AMD].*packages/' sync-data/ohos_adapt_list.txt | awk '{print $3}')

# 以基线版本为三方基准三方合并
git apply --3way <packages 子集 diff>

重放后的真实状态有两层，只看第一层会误判：

1. 磁盘上 0 个冲突标记（没有 <<<<<<<）——看起来「干净」；
2. 但 14 个文件停留在 unmerged 索引态——内容已经正确，git 只是没确认：

# 找出停在 unmerged 态的文件
git diff --diff-filter=U --name-only
# 内容正确，直接确认
git add <上述文件>

「磁盘 0 冲突」≠「合并完成」。git apply --3way 的 3-way 结果可能把冲突静默解决后留在索引里，
必须用 git diff --diff-filter=U 逐个确认——「以为合完了」是三方重放的第一大假象。

2.2 pubspec：两处路径依赖改指本地 fork

重打完还要处理 flutter_tools/pubspec.yaml 的两处路径依赖：code_assets 与 hooks_runner 改指本地 fork（fluttertpc_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   # 本地 fork
  hooks_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——补丁「打了个寂寞」。

根因：dart JIT 二进制内嵌了 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_os="mac"）
python3 tools/build.py --mode release --arch arm64 create_sdk
# 产物：xcodebuild/ReleaseARM64/dart-sdk

两个容易翻车的细节：

• 目录名必须是 sdk：gclient 布局对 checkout 目录名敏感，起别的名字 deps 落位全错；
• --os macos 不存在：build.py 只认 --os host（映射 target_os="mac"）等少数值，传 macos 直接报错。

验证（G2 门的一部分）：

// verify_abi.dart
import 'dart:ffi';
void main() {
  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 文件补丁集：

#	文件	内容	不打的后果
1	lib/ffi/abi.dart	公共 const ×3 + values 列表 + 私有 const ×3 + _OS 枚举加 ohos	运行时 ABI 缺失
2	lib/ffi/abi_specific.dart	文档表 3 行	同上
3	lib/_internal/vm/lib/ffi_patch.dart	指针宽度表 3 行	同上
4	lib/io/platform.dart	static final bool isOhos	Platform.isOhos 无法编译
5	lib/ffi/c_type.dart	15 张表 × Abi.ohosArm/ohosArm64/ohosX64 = 45 行	运行时 IntPtr 表缺行——但编译期 sizeOf 仍过
6	pkg/vm/lib/modular/transformations/ffi/abi.dart	VM 编译器侧 ABI 注册表：镜像 Abi 类 + _OS 枚举 + abiNames map + nonSizeAlignment 表	Type IntPtr has no mapping for ABI (ohos, arm) / Null check operator used on a null value（getAlignmentFor）

第 5、6 个补丁有两个工程细节值得记：

• c_type.dart 用「位置对齐」方案打入：ref（参考实现）减掉 ohos 行后必须与 stock 逐行对齐才敢打；其中 ref 562/604 两处 androidX64 Uint32→Int32 是上游 3.12→3.13 的官方改动，保留 stock 值不动；
• nonSizeAlignment 按平台分组：ohosArm 与 androidArm 同组用 32Align64，ohosArm64/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 的缓存目录，两个动作必须成套做：

# 原版留备份，出问题可秒回退
mv bin/cache/dart-sdk bin/cache/dart-sdk-stock-3.13.3.bak
cp -r xcodebuild/ReleaseARM64/dart-sdk bin/cache/dart-sdk
# engine.stamp 保持不动（仍等于 engine.version 06a2e2a1）

engine.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-O，Windows 的是 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 参考）：

1. .dart_tool/package_config.json 里 sky_engine → file:///…/bin/cache/pkg/sky_engine——确认解析路径；
2. 该 pkg 的 lib/io/platform.dart 无 isOhos——确认缺失；
3. 把 6 个补丁文件 cp 过去即恢复，另加 ui_web 枚举 stub 的 ohos 值：

for f in ffi/abi.dart ffi/abi_specific.dart ffi/c_type.dart \
         _internal/vm/lib/ffi_patch.dart io/platform.dart; do
  cp bin/cache/dart-sdk/lib/$f bin/cache/pkg/sky_engine/lib/$f
done

这是分析期的临时手段。Phase 3 构建 ohos engine 发布包时，
必须让 sky_engine 自带补丁（第 9 篇发布链路的一部分）——临时 cp 只解决「这一台机器」。

四、flutter_tools：13 处 API 漂移的修复

Dart SDK 就位后，./bin/flutter --version 触发的工具链编译爆出 13 个错误——全部是 3.44.9 鸿蒙侧写法与 3.47.4 上游 API 的漂移。主要条目如下：

4.1 漂移修复清单

#	文件	3.44.9 鸿蒙侧用法（报错点）	3.47.4 对应物	修复
1	ohos/hvigor_utils.dart	import '../reporting/reporting.dart'	reporting/ 目录已删（仅剩 crash_reporting/compat）	删 import
2	同上	BuildEvent(...).send()	globals.logger.sendEvent(name, args)	改写两行
3	build_info.dart	旧版顶层 getNameForTargetPlatform 与新版 switch 版重复声明	3way 合并把两个版本都留下了	删旧 wrapper（新 switch 版已含 ohos case）
4	commands/clean.dart	Future<void> 方法内 return FlutterCommandResult	3.47.4 把 run() 拆成 _cleanProject（void）	删 return
5	commands/update_packages.dart	widgetPreviewScaffoldProject（旧属 UpdatePackagesCommand）	移动为 FlutterProject.widgetPreviewScaffoldProject	加前缀 rootProject.
6	build_system/targets/native_assets.dart	ohos 分支引用 dartHookResult	变量改名 combinedResult	改引用
7	build_system/targets/ohos.dart	DartBuild.loadHookResult	类改名 LinkHooks	改类名
8	同上	依赖 DartBuildForNative()	类消失；等价物 LinkHooks()（自带 BuildHooks() 依赖）	换依赖
9	artifacts.dart	_getDartSdkPath 调 _getFlutterPrebuiltsPath(两参)	类内 0 参方法	去参
10	同上	_getPrebuiltTarget(两参)	同上	去参
11	同上	顶层 _getPrebuiltTarget switch 无 ohos case	穷尽匹配失败	补 4 个 ohos case（归入 unsupported 组）

4.2 四类漂移模式

13 处漂移归纳后只有四类，下一批次可以直接按类排查：

1. 改名/搬家（#2、#5、#7、#8）：上游重构把类/方法挪位置——修法固定：以上游新名为准改引用；
2. 参数签名变化（#9、#10）：方法从「带工具依赖参数」改成「0 参」——修法固定：去参；
3. 重复声明残留（#3、#4）：3way 合并的副产品——新旧两个版本都留在文件里，删旧留新；
4. 穷尽匹配缺口（#1、#11）：上游删目录/改 switch——补 ohos case 或删 import。

第 3 类最值得警惕：它是「合并本身制造的问题」，不是「上游改的问题」——
三方重放后的编译错误，先分清属于哪一类，再动手。

五、Phase 1+2 收官：G1+G2 双门通过

5.1 收官状态（落库提交 bd061a09d6）

Phase 2 完成时的验收清单，全部实测通过：

• ✅ 421 文件重打，磁盘 0 冲突 + 14 个 unmerged 全部 git add 销账；
• ✅ Dart 3.13.3+ohos 从源码构建并装机（6 文件补丁集，脚本已固化）；
• ✅ flutter_tools 13 处 API 漂移修复，工具编译通过，版本横幅完整输出：

Flutter 3.47.4 · Dart 3.13.3（ohos 定制）

• ✅ flutter analyze 全量 error = 0（4 个 packages）——G2 门通过；
• _window_ohos.dart 的 5 个 WindowingOwner override 按 3.47.4 新签名重排（size/constraints/resizable），resizable 暂为 no-op（engine 未暴露，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 的三件事）

1. engine 源码获取：engine revision 06a2e2a1 在上游 github 404，需要找替代渠道——Phase 3 的第一个拦路虎；
2. sky_engine 镜像同步：3.5 节的 cp 是分析期临时手段，Phase 4 重建 engine 发布包时应让 sky_engine 自带补丁；
3. 补丁脚本维护：scripts/patch_and_build_dart_ohos.sh 已固化，下一批次换 dart 版本时以它为重放入口。

六、Phase 1+2 复盘：三条可迁移的教训

抛开本项目细节，这两个阶段沉淀了三条对任何「fork 上游同步」都成立的教训：

1. 环境故障优先于一切：本批次 95% 的「不可思议错误」最后都指向前置条件（代理 HTTP/2、缓存镜像、stamp 状态）——排查顺序永远是「环境 → 配置 → 代码」；
2. 「干净」是最危险的表象：磁盘 0 冲突 ≠ 合并完成，编译过 ≠ 运行时对（c_type 补丁）、补丁打了 ≠ 生效（platform kernel）——每个「通过」后面都要问一句「它到底验证了什么」；
3. 隐藏依赖会逐个暴露，要按清单管理：ffi 三件套 → isOhos → IntPtr 表 → VM 编译器 ABI 表 → sky_engine 镜像，每个都是撞出来的——把每次撞出来的依赖当场写进补丁清单/文档，是「下一批次变快」的唯一方式。

七、常见问题 FAQ

7.1 踩坑速查表

域	现象	原因	处理
网络	全量 clone 两次失败（curl 18 / early EOF）	本地代理杀死 HTTP/2 大包	git config --global http.version HTTP/1.1
重放	以为 3way 合并完成（磁盘 0 冲突标记）	14 文件停留 unmerged 索引态	git diff --diff-filter=U 逐个确认 + git add
重放	工具链构建期才报 hooks API 错误	pub 解析了上游 hooks 包	pubspec 两处 path 依赖指本地 fork
Dart SDK	Abi.ohosArm Member not found	dart JIT 内嵌 platform kernel，缓存补丁零影响	从源码构建（3.2 节）
Dart SDK	gclient deps 落位全错	.gclient 必须在父目录、目录名必须恰为 sdk	按布局重做（3.2 节）
Dart SDK	build.py 参数报错	--os macos 是非法参数	用默认 --os host（3.2 节）
Dart SDK	IntPtr has no mapping for ABI	补丁集不完整（3 文件假设不成立）	6 文件补丁集（3.3 节）
analyze	Platform.isOhos undefined	sky_engine/lib 第二镜像无 ohos	cp 6 补丁文件 + ui_web stub（3.5 节）
缓存	engine 工件被意外重下	误改 engine.stamp	stamp 保持等于 engine.version（3.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.4 Platform.isOhos undefined 是怎么回事？

framework 的 flutter analyze 依赖两份 sky_engine：一份在 engine 产物里，一份在 sky_engine/lib 镜像里。只补前者，后者仍没有 ohos 平台定义，analyze 就会报未定义。处理是把 6 个补丁文件同步进第二镜像，并补上 ui_web stub（3.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 1+2 需要什么环境？

Flutter OH 基线 3.44.9（当前发布版 3.47.8-ohos-1.0.0）、上游目标 3.47.4；DevEco Studio 26.0.0 Release + OpenHarmony SDK / API 26；macOS arm64、≥88GB 空闲磁盘、git / python3 / clang / ninja / node。环境变量与工具链配置见官方环境搭建指导。

八、系列导航

「鸿蒙Flutter框架 0day适配实战」全系列 10 篇，本篇为第 6 篇（生产侧 Phase 1+2）：

#	篇目	侧	一句话主题
01	背景、分叉仓库、版本命名与 fvm fork 安装	消费	三层架构、三个接缝、七层工作量、fvm 直装 tag、版本墙
02	tag 版本的手动安装与三层核验	消费	浅克隆 bootstrap、首次初始化、SSH 修复、异常分诊
03	鸿蒙模拟器/真机跑 Flutter + 消费侧踩坑集	消费	工具链三件套、HAP 构建/安装/运行、占位签名、截图取证、CP1-CP14
04	flutter build hap 自动签名	消费	P12/CSR、AGC 证书与 Profile、纯 Dart AES-GCM、C0-C10 复用
05	上游同步总览、BC 全景与端到端 SOP	生产	批次解剖、五阶段验证门、12 项适配表、端到端 SOP 与 P1-P29 索引
06	Phase 1+2：基线建立与 Framework 适配（本篇）	生产	代理 HTTP/1.1 修障、421 文件重打、Dart SDK 源码构建
07	Phase 3 Engine：三方重放与冲突裁决	生产	826 文件、15 真冲突两分法、契约对齐 16 项
08	引擎构建链攻防	生产	依赖树、工具链版本、链接与测试面 27 坑
09	构建发布与产物分发	生产	版本锁、11 个工件（Dart SDK 双宿主）、11 条覆盖键、换新 tag 铁律
10	验证与真机验收	生产	三档引擎、设备侧单测、字体图标静默故障

配套仓库与文档：

• 鸿蒙分叉仓库（当前主线 3.47.8-ohos-1.0.0）：atomgit.com/oh-flutter/flutter_flutter
• 上游 Flutter 仓库：github.com/flutter/flutter
• Dart SDK 源码（3.2 节构建对象）：github.com/dart-lang/sdk
• 本地 fork 的 dart native 包（2.2 节路径依赖）：atomgit.com/hxa-flutter/fluttertpc_dart_native
• Flutter OH 环境搭建指导：OpenHarmony-flutter 环境搭建指导
• Flutter 官方文档：docs.flutter.dev
• Dart 官方文档：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 error（G2 门），收官于 commit bd061a09d6。三条复盘教训（环境优先、「干净」最危险、隐藏依赖按清单管理）对任何 fork 同步都成立。

下一篇（第 7 篇）进入 Phase 3——全批次工作量最高的 engine 侧：826 文件重打、15 个真冲突的两分法裁决，以及契约对齐 16 项（G3 门）。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• Flutter OH 环境搭建指导：OpenHarmony-flutter 环境搭建指导
• 分叉仓库（3.47 线，当前发布 3.47.8-ohos-1.0.0）：atomgit.com/oh-flutter/flutter_flutter
• 上游 Flutter 仓库：github.com/flutter/flutter
• Dart SDK 源码：github.com/dart-lang/sdk
• 本地 fork 的 dart native 包：atomgit.com/hxa-flutter/fluttertpc_dart_native
• Flutter 官方文档：docs.flutter.dev
• Dart 官方文档：dart.dev
• 开源鸿蒙跨平台社区：openharmonycrossplatform.csdn.net

环境与版本

本文的示例与截图基于以下环境组合（2026-10 实测）：

组件	版本	说明
上游 Flutter SDK	3.47.8	github.com/flutter/flutter
Flutter SDK（OH 适配版）	3.47.8-ohos-1.0.0	oh-flutter/flutter_flutter，oh-3.47-dev 分支
DevEco Studio	26.0.0 Release	提供 hvigor / ohpm / hdc / JBR 等工具链
OpenHarmony SDK / API	API 26（26.0.0）	模拟器与 SDK 均为 API 26
运行设备	OpenHarmony 模拟器	API 26，1280×2832

环境搭建（分叉获取、DevEco Studio 与 SDK 配置、模拟器创建）请按官方指导操作：OpenHarmony-flutter 环境搭建指导。

本文正文是 2026-09 3.44.9 → 3.47.4 同步批次的实录：其中的版本号、提交号与实测数字（适配清单文件数、构建边数、单测用例数、工件字节数等）都是那一批的现场值，不随上表更新；上表是当前可复现、可照做的环境组合。方法论、验证门与坑模型对 3.47.8 线同样适用。