林毅轩前阵子我在处理后台日志时，反复要做同一件事：把一段压缩成一行的 JSON 格式化、核对结构、提取某个字段。在电脑上靠编辑器插件还能忍，到了手机上就特别别扭。正好手头有一台鸿蒙平板，我就决定把这个自建 JSON 解析工具 App 用 Flutter 移植到 HarmonyOS 6 上。整个过程踩了不少坑，也把 JSON 工具该有的几个能力重新梳理了一遍。这篇博文会从环境搭建讲到数据层架构，再讲到格式化、校验、字段提取这些核心功能的实现，最后是真机调试和打包的注意事项，希望能给同样在做 Flutter + HarmonyOS 方向的开发者一些参考。
1. 为什么这个 JSON 工具值得做成 Flutter + HarmonyOS 的 App
1.1 一个从"自己复制粘贴到手软"开始的真实需求
很多人低估了一个 JSON 格式化工具的价值，觉得浏览器里随便开个网页就行。但在实际开发中，我经常要处理的是后端接口返回的"一行式 JSON"——几百上千个字符挤在一起，键值对看不清、嵌套层级找不到，最要命的是一旦里面混入了异常数据，肉眼根本定位不出来。
更麻烦的是场景。很多时候我是在外面、在地铁上、在客户现场看日志，电脑不在手边。手机上用网页工具也不是不行，但要联网、要忍受广告，更重要的是数据要从手里过一遍第三方服务器，这在处理公司接口日志时是明显不能接受的。我需要的工具其实很朴素：完全离线运行、支持格式化、能告诉我哪一行语法错了、还能按路径快速取字段，打开就能用，不卡不弹广告。
于是这个 App 的定位就定了：一个本地优先的 JSON 解析工具，数据不出设备，核心能力就是格式化、校验、字段提取，再加一个文件读取和剪贴板交互。
1.2 为什么选 Flutter 而不是 ArkTS 或 Web 套壳
拿到鸿蒙设备后，第一反应是先看原生方案。HarmonyOS 上最正统的思路是用 ArkTS 写一个原子化服务或应用，这条路本身没有问题，Ark 语言的声明式 UI 用得顺手的话开发效率也不低。但对我这个项目来说有个现实问题：我后续会在 Android 和 iOS 上也需要同样一个工具。如果只在 ArkTS 里写一遍，等于之后要重写两遍；如果选 Flutter，核心解析逻辑、界面结构、状态管理都能复用，鸿蒙只是打包目标之一。
有人会问，Web 套壳不是更省事吗？把网页包进 WebView 就能跑。这个方案我实际试过，做工具类 App 有两个硬伤：一是文件读取、剪贴板、系统分享这些系统能力的体验依赖桥接层，做起来并不比原生少；二是冷启动速度和页面切换流畅度，跟 Flutter 编译出来的原生代码还是有差距。作为一个高频使用的开发工具，响应速度本身就是核心体验。
Flutter 在鸿蒙上的现状是：虽然官方主干对 OpenHarmony 的适配还在推进，但社区分支已经可以把 Flutter 工程跑到鸿蒙设备上，DevEco Studio 负责底层构建，Flutter 层负责 UI 和业务逻辑。我实际跑下来的感受是，常规的 dart:convert、async、File IO 这些能力都没问题，社区常用插件也有对应兼容版本。到现在这个工具在我平板上稳定跑了快两个月，没出现过明显兼容性问题。
1.3 这个项目适合谁跟练
如果你属于下面三类人，这篇内容会比较有参考价值：第一类是已经在做 Flutter、手里有鸿蒙设备、想试试跨端落地的开发者；第二类是准备用鸿蒙版 Flutter 开发小工具类 App 的人，可以照着我这个项目结构去做功能规划；第三类是对 JSON 解析细节感兴趣，特别是想搞清楚 jsonDecode 之外还需不需要做更多设计的人。
不管你是只想要一个能用的 JSON 工具，还是想学 Flutter + HarmonyOS 的工程化链路，这篇文章都会按实际开发顺序来讲，不是那种只讲思路不给代码的泛泛而谈。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 工程接入：Flutter 连上鸿蒙构建链路的那些坑
2.1 工具链组合与基本环境准备
先把我的工具链组合列出来，方便对照：
| 组件 | 我用的版本/方案 | 说明 |
|---|---|---|
| 操作系统 | Windows 11 / macOS 双环境 | 构建产物略有差异，但流程一致 |
| Flutter SDK | 基于 OpenHarmony 社区适配分支 | 比官方主干多了 hap 构建目标 |
| HarmonyOS SDK | DevEco Studio 内置对应版本 | 需要确认 SDK 级别满足目标设备 |
| Dart SDK | 随 Flutter 分支自带 | 保持版本匹配即可 |
| 开发 IDE | VS Code + DevEco Studio | VS Code 写业务，DevEco 管签名和部分构建 |
环境准备阶段最容易踩的第一个坑是 Flutter SDK 的版本。不要随便从官网拉一个最新稳定版就跑，鸿蒙适配分支的版本号和官方不是完全同步的。我一开始用官方分支跑，果不其然 flutter build hap 这个命令根本不认识。换成社区适配分支之后，还需要在 flutter doctor 里检查一下有没有识别到鸿蒙开发环境。
然后是你本机的镜像配置。为了下载依赖更快更稳，建议把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 这两个环境变量指向国内可用的镜像源。这一步不是可选项，至少在我所处的网络环境下，不配置的话下载 Dart 包和 Flutter 引擎产物会非常折磨，而且经常卡到中断。配置完之后，flutter doctor 会显示通过，说明依赖下载路径已经通了。
DevEco Studio 这边，安装后要打开 SDK Manager 确认 HarmonyOS SDK 组件已经下载完整。很多人在这里会漏掉 Native 相关组件，导致后面编译时报找不到 SDK 的奇葩错误。
2.2 Gradle 插件管理的兼容性坑
工程搭建后半段，我遇到了这篇项目里最想吐槽的一个问题：Gradle 插件依赖冲突。这个报错在开发者社区里也很常见，大致意思是说你正在用命令式 apply 的方式引入 Flutter 主插件，但项目配置里又走了声明式 plugins DSL，两边打架了。我那次实际看到的报错长这样：
text复制you are applying flutter's main gradle plugin imperatively using the apply script method, which is not supported
这个问题的根源是 Flutter 鸿蒙分支对 Gradle 插件加载方式做了调整。老项目里常见的写法是：
gradle复制apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle"
在鸿蒙分支的构建链路上，这段逻辑被要求改成 plugins DSL 方式，也就是说要在 `