企业官网建设流程全解析

去年开始，我陆续把手头的几个 Flutter 应用往鸿蒙上迁移。UI 层面的适配还好说，真正让我头疼的是网络调试这一块。原来用的是flutter_pretty_dio_logger这个三方库，在 Android 和 iOS 上打印出来的 Dio 请求日志又规整又直观，可一放到鸿蒙（HarmonyOS NEXT）环境里，各种问题就冒出来了：日志不输出、中文字符变成乱码、甚至构建阶段直接报错。

我把这套适配过程完整梳理了一遍，包含我实际改过的代码、验证过的配置，以及填过的几个大坑。如果你正在做鸿蒙化改造，或者打算把 Flutter 应用搬上鸿蒙生态，这篇指南可以帮你省下不少时间。

1. 为什么flutter_pretty_dio_logger在鸿蒙上会“水土不服”

1.1 这个库到底解决了什么问题

先简单交代一下背景。flutter_pretty_dio_logger是 Dart 生态里比较流行的网络日志拦截器，它基于 Dio 的拦截器机制工作。Dio 发起的每个请求，都会经过拦截器链，这个库就是在这里截获请求和响应数据，然后用一种非常“漂亮”的格式打印到控制台里。

它解决的问题很具体：第一，开发者能直观看到每个请求的完整链路，包括 Method、URL、Headers、Query Parameters、Request Body、Response Body 这些关键信息；第二，它支持对敏感字段做脱敏处理，比如密码、token、Cookie 这类信息，默认会用占位符遮蔽；第三，它支持折叠打印、响应体截断、超时时间展示等细节控制，比 Flutter 自带的 debugPrint 输出要专业得多。

我在原来的项目里是这么用的，只需要在初始化 Dio 时挂上拦截器：

final dio = Dio( BaseOptions( baseUrl: 'https://api.example.com', connectTimeout: const Duration(seconds: 15), receiveTimeout: const Duration(seconds: 15), ), ); dio.interceptors.add( PrettyDioLogger( requestHeader: true, requestBody: true, responseBody: true, responseHeader: false, error: true, compact: false, maxWidth: 90, filter: (options, args) { // 不打印请求体包含 password 的日志 if (options.data is Map && (options.data as Map).containsKey('password')) { return false; } return true; }, ), );

这套配置在 Android、iOS、macOS 上都跑得很稳。但同样的代码迁移到鸿蒙，问题就来了。

1.2 鸿蒙化背后的三条技术挑战

先说清楚鸿蒙环境下 Flutter 的特殊性，这是理解后面所有适配操作的前提。

首先，鸿蒙 NEXT 去掉了 AOSP 兼容层，Flutter 官方 SDK 不能直接跑在鸿蒙上。目前能用的方案是 OpenHarmony 社区维护的 Flutter 引擎分支，也就是flutter_flutter仓库的harmony分支，配合 DevEco Studio 里生成的ohos平台目录。这意味着很多 Android/iOS 上默认行为，在鸿蒙上都需要重新验证一遍。

其次，flutter_pretty_dio_logger表面上是个纯 Dart 库，但它的输出行为依赖debugPrint和dart:io的 stdout。鸿蒙的 Flutter 引擎虽然也实现了 dart:io，但在日志输出通道上跟 Android 不完全一致。Android 上会走 Logcat，而鸿蒙上如果没有接入 hilog，日志可能在控制台完全看不到——这不是库的问题，是输出通道断了。

第三，Dio 底层网络栈在不同平台上的行为差异，也会影响日志内容的真实性。鸿蒙的 socket 实现、TLS 证书校验逻辑、DNS 解析跟 Android 都有细微差别，比如某些自签名证书在 Android 上能通过，在鸿蒙上握手直接失败。这时如果日志模块没有适配好，你看到的就是一个孤零零的异常，完全定位不到是哪一层抛出来的。

2. 适配前的整体设计：先想清楚再动手

2.1 明确适配边界：改库还是桥接

拿到一个三方库做鸿蒙化，通常有三条路：

• 直接把源码复制到本地，改到能跑为止。优点是可以随意改动，缺点是要维护一份私有副本，后续上游更新得手动合。
• 写一个中间适配层，用组合的方式替换掉目标库的行为。优点是不动原库，缺点是像PrettyDioLogger这种实现比较完整的库，组合成本很高。
• 放弃原库，基于 Dio 拦截器自研一个轻量日志器。

我在这个项目里选了第一个方案：fork 一份代码到项目内的third_party目录，以本地依赖的方式引入。原因很简单，flutter_pretty_dio_logger的核心功能做得已经很完善，脱敏正则、折叠打印、请求体格式化这些，自研要花不少时间。鸿蒙化真正要动的只是输出通道、字符编码、以及平台差异的兜底逻辑，改造成本可控。

适配的边界我也划得很明确：保持原库对外 API 完全不变，内部增加鸿蒙平台分支处理。这样应用层代码一行都不用改，后续如果需要切换到其他方案，影响面可控。

2.2 鸿蒙化适配的技术选型

核心选型是这样的：用 OpenHarmony 的 Flutter 引擎作为运行时，配合 Flutter 官方工具链生成ohos平台目录，然后在原生侧通过 hilog 接管日志输出，Dart 侧保持PrettyDioLogger的接口和拦截器逻辑不变。

这里有一个好消息：flutter_pretty_dio_logger依赖的拦截器机制是纯 Dart 层的，Dio 的拦截器在鸿蒙引擎上同样正常工作。真正需要动刀的是日志输出那一层。默认实现里用的是debugPrint，它在鸿蒙引擎上有可能因为 stdout 的 write 行为不同，导致输出不完整或直接丢弃。我的处理方式是增加一个可配置的logOutput回调，让调用方决定日志往哪去。

同时，还需要解决平台侧的最小依赖问题。原库是纯 Dart 的，不该依赖任何原生平台通道。但鸿蒙化之后，为了让日志能出现在 DevEco Studio 的 hilog 面板里，我们需要在原生侧做一个很小的通道适配。最优雅的做法是让 Dart 侧输出到一个静态方法，原生侧通过MethodChannel注册日志回调，然后调用HiLog.info写入鸿蒙日志系统。

2.3 需要准备的代码基线与验证环境

动手之前，先把环境和版本基线确认好，否则后面会陷入“同样的代码，换个机器就报错”的泥潭。

我验证时使用的版本组合是这样：

需要说明的是，鸿蒙的 Flutter 社区分支迭代速度很快，不同的 commit 可能对应不同的引擎能力。建议锁定一个 release 版本，别追最新代码。我在迁移过程中遇到过好几次“昨天还好好的，今天 pull 完就编不过”的情况，最后都是切回固定的 tag 解决的。

模拟器方面，鸿蒙模拟器目前对 Flutter 应用的支持还不够稳定，尤其是涉及网络请求和日志输出的场景，建议有条件直接上真机。真机调试时通过 hdc 连接设备，在 DevEco Studio 的 Log 面板里可以实时看到 hilog 的输出。

3. 实操：从接入到跑通的核心环节

3.1 改造依赖声明：本地副本引入

第一步，把库源码放进项目。我建议在工程根目录建一个third_party/flutter_pretty_dio_logger目录，然后把源码复制进去。这样后续修改本地副本，pubspec.yaml里直接指向本地路径，不依赖远程 Git 仓库，也避免因为仓库访问问题导致构建失败。

pubspec.yaml里原来的写法是：

dependencies: flutter_pretty_dio_logger: ^3.0.0

改为：

dependencies: flutter_pretty_dio_logger: path: third_party/flutter_pretty_dio_logger

然后执行flutter pub get。这里要注意，如果项目里同时有ohos平台目录，务必确认flutter pub get之后ohos目录下的依赖配置没有被动过。鸿蒙工程里有一个ohos/entry/oh-package.json5，这个文件偶尔会被 pub 工具重写，导致原生依赖丢失。我建议跑完 pub get 之后检查一下oh-package.json5，如果内容变了，先git checkout回去。

3.2 处理原生侧：日志输出通道切换

接下来是核心改动。打开 fork 后的pretty_dio_logger.dart，找到logPrint相关逻辑。原来的实现大概是：

void _logPrint(String message) { debugPrint(message); }

鸿蒙化之后，我们需要让日志同时进入 hilog。做法是加一个可配置的日志输出函数：

typedef LogOutput = void Function(String message); class PrettyDioLogger { PrettyDioLogger({... this.logOutput = defaultLogOutput}); static void defaultLogOutput(String message) { // Android / iOS / desktop 沿用 debugPrint debugPrint(message); } }

然后，在应用初始化时，把函数替换成鸿蒙适配版本。这里需要先注册一个 MethodChannel，让 Dart 侧可以调用原生侧的 hilog。以entry/ohos目录为例，在EntryAbility.kt里增加 channel 处理逻辑：

override fun onStart(want: Want, launchParam: LaunchParam) { super.onStart(want, launchParam) flutterEngine?.dartExecutor?.setMethodChannelHandler( "flutter_pretty_dio_logger/logger" ) { call, result -> if (call.method == "log") { val message = call.argument<String>("message") ?: "" HiLog.info(LABEL, "%{public}s", message) result.success(true) } else { result.notImplemented() } } }

Dart 侧对应实现：

import 'package:flutter/services.dart'; void initOhosLogger() { const channel = MethodChannel('flutter_pretty_dio_logger/logger'); PrettyDioLogger.logOutput = (message) { debugPrint(message); channel.invokeMethod('log', {'message': message}); }; }

这里有两个细节值得注意：

1. HiLog 的隐私标记。HiLog.info的参数格式化，如果字符串包含敏感信息，建议用%{public}s，否则默认%{private}s会把内容打码成{private}，反而看不到日志。调试阶段直接用%{public}s最方便。
2. MethodChannel 的调用频率。网络请求多的时候，日志量非常大，每一个消息都走 channel 会有一定性能损耗。实测下来，如果每秒打印超过 100 条日志，UI 线程有可见卡顿。优化方案是做一个简单的批量缓冲，攒够 50 条或者 500ms 再一次性发给原生侧。这个我在后面章节细说。

3.3 Dio 拦截器接入与全局配置

Dart 侧的配置基本沿用之前的方案，但有几个参数在鸿蒙环境下需要额外注意。

我最终在项目里的配置是这样：

final prettyLogger = PrettyDioLogger( requestHeader: true, requestBody: true, responseBody: true, responseHeader: false, error: true, compact: true, maxWidth: 120, maxDepth: 4, filter: _logFilter, logOutput: isOhos ? initOhosLoggerOutput() : null, );

maxWidth在鸿蒙上建议不要超过 120。因为 DevEco Studio 的 log 面板宽度和 Android Logcat 不一样，行宽过大会导致日志被截断，反而丢失信息。compact: true也推荐打开，它会压缩一些无用的空行，在鸿蒙控制台面板上阅读起来更舒服。

_logFilter里我做了一个请求级别的过滤，把上传大文件的请求排除掉，避免控制台被大量二进制内容刷屏：

bool _logFilter(RequestOptions options, Object? args) { if (options.data is FormData) { return false; } return true; }

这个过滤方法也解释了为什么我要一开始保持原库的 API 不变——应用层已经写好的过滤逻辑，可以直接复用。

3.4 日志脱敏的正确姿势

日志脱敏是flutter_pretty_dio_logger的招牌能力，也是我在鸿蒙适配里花时间最多的地方。原库内部有一套基于正则的脱敏机制，默认匹配的是常见字段名，比如password、authorization、cookie这类。但实测下来，这套逻辑在鸿蒙场景里存在两个问题：

一是正则对中文参数名的覆盖不够，比如部分接口里用的手机号、身份证这种自定义字段，原库就不会处理；二是脱敏只作用于打印层，如果后续把日志上传到远端做分析，脱敏就失效了。

我的做法是在 fork 后的库里增加一个sanitizers列表，让调用方可以追加自定义脱敏规则：

class PrettyDioLogger { final List<PrettyDioSanitizer> sanitizers; } class PrettyDioSanitizer { final RegExp pattern; final String replacement; }

在日志输出前，对 body 和 header 依次执行所有 sanitizer。例如针对身份证号的脱敏：

PrettyDioLogger( sanitizers: [ PrettyDioSanitizer( pattern: RegExp(r'(\d{6})\d{8}(\d{3}[\dXx])'), replacement: r'$1********$2', ), PrettyDioSanitizer( pattern: RegExp(r'(?<=[\u4e00-\u9fa5]手机号["\s:=]+)\d{11}'), replacement: '***********', ), ], )

这里面的正则写起来比较费劲，但值得做。脱敏规则越具体，上线后越不担心日志泄露问题。另外我还加了一个安全开关——当Release模式下强制开启脱敏，并且禁用响应体打印，防止线上日志把用户数据刷出去。

4. 网络请求可视化与协议调试治理的进阶玩法

4.1 关键指标观测：耗时、状态码与错误归类

日志脱敏解决了“安全”问题，真正的“可视化”还需要更多维度。我在适配过程中发现，仅仅把日志漂亮地打印出来，还远远不够。调试一个复杂问题，尤其是线上问题，最缺的是三个指标：单次请求耗时、接口成功率、错误归类。

利用 Dio 拦截器的onRequest和onResponse，我扩展了PrettyDioLogger的能力。在请求开始前记录时间戳，在响应返回后计算耗时，然后追加到日志末尾：

@override void onRequest(RequestOptions options, RequestInterceptorHandler handler) { _startTimeMap[options.hashCode] = DateTime.now(); super.onRequest(options, handler); }

然后在输出日志时，把耗时信息拼进去。这一步对原库的改动不大，但对诊断问题非常有用。比如在鸿蒙上，DNS 解析偶尔会比 Android 慢上几百毫秒，通过日志里的耗时分布，能很快发现是网络链路问题还是接口本身慢。

状态码和异常的分类，我也做了结构化处理。响应码 2xx、3xx、4xx、5xx 分别用不同的调试级别输出，网络异常和业务异常分开展示。这样在 DevEco Studio 的日志面板里过滤时，可以快速定位到 5xx 或者超时记录，不用一条条翻。

4.2 运行时动态调节日志粒度

日志量越大，找到目标问题的成本越高。我在鸿蒙适配版本里增加了一个按需开关：日志粒度分三级。

• Level.basic：只打印方法、URL、状态码、耗时。
• Level.detail：在 basic 基础上，增加 headers、query、简短响应体。
• Level.body：完整打印请求和响应体，一般只在需要排查数据问题时开启。

这个开关设计成运行时可调，没必要重新编译。我在应用里做了个悬浮按钮，调试模式下点一下就能切换级别。这个功能上线后，团队成员反馈很好，因为不需要改代码、重新 build，直接在真机上切换即可。

切换逻辑借助一个静态变量或 ValueNotifier 实现：

class LoggerLevelNotifier { static final ValueNotifier<LogLevel> current = ValueNotifier(LogLevel.basic); }

在PrettyDioLogger内部输出前判断一下当前级别，决定打印多少内容。这个方案实现成本不高，但让整个日志模块的可用性提升了几个档次。

4.3 发布治理与性能兜底

鸿蒙应用上线之后，日志模块不能就这么裸奔。我做了三件收尾的事。

第一，Release 模式下强制关闭响应体打印。无论PrettyDioLogger配置里responseBody是不是 true，只要kReleaseMode为真，一律置为 false。这样线上出问题只能看到请求概况，看不到具体响应数据，但仍然保留请求耗时和状态码，可以用于告警和快速定位。

第二，把日志模块包在一层条件判断里，生产环境甚至可以走一个空实现的拦截器。这一步能省掉不必要的字符串拼接开销，避免日志格式化拖慢网络请求。

第三，做日志缓冲。前面提到 MethodChannel 高频调用会卡 UI，我最终实现了一个批量上报的方案：Dart 侧先把日志存到一个List<String>，每满 50 条或 500ms 定时器到点，统一通过 channel 发到原生侧。实测连续刷几百条日志，UI 帧率不再掉。

5. 常见问题与排查技巧实录

把这次适配过程中遇到的最典型的问题整理成了速查表，按出现频率排序，方便你排查时直接对照。

补充两个我跟团队成员反复强调的排查细节。

第一个是“日志不输出先怀疑通道”。很多人遇到鸿蒙下日志显示不出来，第一反应是代码逻辑写错了，去翻一整天 Dart 代码。其实 90% 的情况是输出通道的问题——默认的debugPrint在鸿蒙上行为非常不稳定。把日志输出切到 hilog 之后，问题基本都消失了。

第二个是“别忽略异常里的堆栈”。鸿蒙引擎的 Dio 异常堆栈格式跟 Android 略有不同，有些调用链在控制台上会显示不全。如果遇到SocketException或者 handshake 错误，推荐再加一个onError回调打印原始堆栈。实测这个方法能帮我们定位到一个很隐蔽的 DNS 解析问题——鸿蒙某些版本对 IPv6 地址的优先级处理跟 Android 不一致。

6. 少走弯路的几个建议

基于这次整包迁移的实践，最后分享几条我用真金白银换来的经验。

DevEco Studio 的日志面板里默认会给 hilog 加过滤，如果你发现日志输出时有时无，检查一下面板的过滤条件。有时候系统日志和 Flutter 日志混杂，按 tag 过滤能清爽很多。我在初始化HiLog时指定了统一的 tag 常量，这样在面板里按 tag 筛选，能直接看到所有网络日志，非常方便。

另外，鸿蒙的 Flutter 引擎迭代速度不比 Flutter 官方慢，社区分支隔一段时间就会调整dart:io的底层实现。适配好的日志库，建议在仓库里写清楚“当前验证的引擎版本”，后面升级引擎时，升级前先跑一遍日志用例，能避免很多隐性回归。

个人体会是，鸿蒙化的核心难点其实不在 Dart 层，而在于对鸿蒙原生运行时的理解。flutter_pretty_dio_logger这种纯 Dart 库，适配成本低、收益高，很值得优先推进。真正要花心思的是日志输出链路、脱敏规则设计和性能兜底策略，这些做好了，整个应用的可观测性就有了一个很扎实的底座。