企业官网建设流程全解析

做跨平台开发这些年，我最大的感触是：框架给的只是起跑线，真正拉开差距的是把业务落到底层设备上的那一段路。最近我把一个 Flutter 框架的在线小说阅读器从零搭到了鸿蒙设备上，这段经历让我重新理解了“跨平台”三个字的含义——你依然写 Dart，绝大多数业务代码原封不动复用，但环境配置、字体排版、权限管理、真机调试这些环节，每个都能让你卡上半天。这篇文章就把整个开发过程拆开来讲，从环境准备到架构设计，从阅读器分页到缓存策略，再到鸿蒙真机上的适配细节，逐个环节给出可复用的方案。

先说我做的是什么：一个支持书架管理、书城推荐、在线章节加载、离线缓存和本地续读的小说阅读器。技术上走 Flutter 跨平台路线，最终产物要同时覆盖 Android 和鸿蒙。之所以选在线小说阅读器作为落地项目，是因为它比普通的“表单+列表”App 更能暴露框架的真实水平——正文排版、翻页手势、长列表性能、大量文本缓存，哪一个做不好，用户都能直接感受到。

1. Flutter 跑在鸿蒙上的底层逻辑：为什么这一步值得做

1.1 Flutter 在鸿蒙生态里的真实位置

很多刚接触这个方向的开发者会有一个误解：觉得鸿蒙适配就是把 Flutter 的 Android 产物装上试试。实际不是这样。Flutter 在鸿蒙上运行，走的是 OpenHarmony 适配分支维护的 Flutter 引擎，它不是在 Android 兼容层里跑的，而是直接对接鸿蒙的图形栈和输入事件。

这意味着两件事值得高兴：

• 你的 Dart 业务代码、Widget 树、动画系统，几乎可以 100% 复用；
• 渲染性能并不是“套壳翻译”，而是 Flutter 自己的 Skia/Impeller 渲染路径，在阅读器这种大量文字刷新的场景下，帧率表现可以做到和 Android 持平甚至更好。

但也意味着另一件事：你不能再把鸿蒙当作 Android 的“亲戚”来处理。插件生态、权限模型、包构建方式、日志工具，全都是一套独立体系。开发在线小说阅读器时，我用了不少常用 Flutter 插件，其中一部分在鸿蒙上根本没有对应实现，这个时候的正确做法不是找替代品硬凑，而是回到 Flutter 自身能力去解决。

1.2 为什么小说阅读器是跨平台适配的绝佳试金石

选阅读器做跨平台项目，是因为它的性能敏感点刚好覆盖了 Flutter 在鸿蒙上容易出问题的区域。

第一个敏感点是文字排版。小说章节动辄几千字，用户还会调整字号、行距、背景色，每次调整都要重新分页，这个过程如果分页算法写得粗糙，翻页就会有明显掉帧。第二个是列表性能。书架和章节目录都是长列表，封面图加载、滚动回收、索引定位缺一不可。第三个是缓存策略。在线小说最核心的用户体验就是离线阅读和断点续读，这要求本地存储和网络加载之间做到无缝衔接。

这三个点全部踩一遍，基本就把 Flutter 跨平台开发的大半个知识图谱覆盖了。

2. 环境准备：SDK 版本、part 语法与工具链联动

2.1 SDK 版本选择：别用最新，用“被验证过”的那个

我在这步吃过亏。一开始图省事装了最新的稳定版 Flutter，结果创建鸿蒙工程时工具链直接提示了一个常见但不友好的信息：

The current configured Flutter SDK is not known to be fully supported.

这个报错的意思是当前 SDK 版本不在鸿蒙适配分支的验证列表里。它不一定直接导致失败，但后续跑构建、生成鸿蒙 runner、打包 .hap 的时候，各种莫名其妙的问题都会冒出来，而你很难判断到底是不是版本引起的。

后来我换了做法：先确认鸿蒙适配分支对应的 Flutter 版本，锁定大版本，不追小版本更新。iOS 和 Android 日常开发继续用原来的 SDK 没问题，但涉及鸿蒙构建时，统一走鸿蒙适配分支这套工具链。项目里最好用一个.fvmrc或脚本锁版本，团队协作时避免出现“我本地能跑你本地不能跑”的情况。

2.2 工程创建与鸿蒙 runner 的生成

拿到合适的 SDK 之后，创建工程的方式和普通 Flutter 项目类似，但多了一步生成鸿蒙侧壳工程的环节。生成的目录里除了 android/ 和 ios/，会出现一个独立的鸿蒙工程目录。

这个目录里有一个容易忽略的点：应用 ID、包名、权限声明，都是在鸿蒙侧配置文件里修改的。比如网络权限、存储权限，如果你在 Android 的 AndroidManifest 里声明了却忘记在鸿蒙侧声明，iOS 上跑正常、Android 上跑正常，到了鸿蒙真机就有可能出现“请求发出去了，但一直超时”的怪问题。

这里我建议把权限清单做成一张对照表，每次加权限时三个端同步检查。阅读器最常用的权限就三类：

2.3 突然想聊一句 “flutter 中 part” 的用法

整个项目代码量上来之后，我重新用上了 Dart 的part关键字。现在很多新项目推荐直接用多个独立文件加 import，但在阅读器这个场景里，一个章节缓存模块内部有数据模型、缓存键生成规则、序列化逻辑、GC 回收策略，这些逻辑是强内聚的，拆成多个 public 文件反而暴露太多内部接口。

用part可以把这些文件收拢在同一个库内部，外部只能看到你暴露的一个入口类：

// chapter_cache.dart library chapter_cache; part 'chapter_cache_model.dart'; part 'chapter_cache_keys.dart'; part 'chapter_cache_serializer.dart'; class ChapterCache { // 外部只关心这个入口 }

这样做的好处是切换阅读器字号重新分页时，缓存模块的内部结构调整不会影响外部调用。但也要注意，part文件内部不能有 public 的重复定义，索引 lint 如果没配好，容易埋雷。所以我的建议是：强内聚模块用 part 收拢，普通页面层还是多个文件 + import 的方式更清晰。

2.4 启动图与构建产物

鸿蒙工程的启动图跟 Android 的 LaunchTheme 和 iOS 的 LaunchScreen 都不同，不要直接复制另外两端的资源。最稳妥的做法是生成几张不同分辨率的纯色或品牌图，放进鸿蒙工程的 media 目录，再在配置里指定。构建产物方面，Flutter 鸿蒙适配分支最终打包出的是.hap文件。第一次打包如果发现产物体积比 Android 大不少，不用惊讶，建议把--split-per-abi或等价的拆分参数加上，按架构拆包后，应用市场可以按设备架构分发，实际下载体积能小很多。

3. 在线小说阅读器的功能拆解与数据层设计

3.1 阅读器的功能清单

动手写代码前，我先列了一份功能优先级清单。在线小说阅读器看上去简单，但想清楚边界后事情就多了：

• 书城：小说列表、分类筛选、搜索；
• 书籍详情：简介、章节目录、开始阅读入口；
• 阅读器：章节正文展示、翻页、字号/行距/背景调整、夜间模式、进度跳转；
• 书架：本地收藏、最近阅读排序、删除；
• 离线逻辑：章节自动缓存、已缓存标记、离线可读；
• 持续记录：本次阅读位置、上次阅读位置、阅读时长。

这份清单最后落到两个核心原则上：阅读体验优先、离线可用兜底。所有功能如果在这两个原则上产生冲突，优先保阅读体验。

3.2 数据模型设计

阅读器领域的数据模型不复杂，但设计不好后面写缓存和续读会非常别扭。我最终稳定的模型如下：

class Book { final String id; final String title; final String author; final String coverUrl; final String intro; final String category; final int chapterCount; } class Chapter { final String bookId; final int index; final String title; final String content; final int wordCount; } class ReadProgress { final String bookId; final int chapterIndex; final int charPosition; final DateTime updatedAt; }

ReadProgress是我特意单独拆出来的。很多新手会把阅读进度塞进 Book 的字段里，短时间看没问题，但一旦要做“最近阅读书架排序”和“多端进度同步”，进度字段和书籍基础信息耦合在一起会特别痛苦。拆开之后，更新进度只需要写一条很轻量的记录，不需要把整本书的信息都加载到内存里。

3.3 状态管理选型：Riverpod 在阅读器的实践

项目中我选了 Riverpod 作为状态管理方案。原因不是它比别的方案高级，而是阅读器这个场景有非常典型的跨页面共享状态：书架页需要知道哪些书有缓存，详情页需要知道当前进度，阅读器需要同步书签变更。用 Riverpod 的AsyncNotifier配合StreamProvider可以很自然地处理这种多层依赖。

举个例子，书架页的数据并不是简单的“从接口拉一次就完事”，它要时刻反映本地缓存变化。我用一个Provider监听数据库变化，再结合网络列表进行合并展示。这样在阅读器里下载完一章、回到书架，列表自动刷新，不需要手动触发setState或者发一个全局事件。

4. 书架与书城页面的工程化实现

4.1 书架列表：混合数据源的合并策略

书架的列表数据由两部分组成：本地缓存的书籍元信息，以及从接口拉取的封面图、最新章节号等实时信息。直接做法是先查本地，拿出最近阅读时间排序的书籍 ID，然后按批去请求远程信息，最后合并渲染。

这里有个体验细节：如果每次进入书架都等网络请求完成再显示，弱网下用户会看到白屏。所以列表要设计成“本地先行，后台刷新”。本地有数据就先渲染出来，网络数据到了再 diff 更新。Flutter 的ListView在数据量不大（几百本以内）时，直接用AnimatedSwitcher做刷新动画也不会卡。

4.2 封面加载与图片缓存

小说封面的加载量不小，书架一屏大概 8 到 12 本，快速滑动时如果每次都走网络，即便是内存缓存也扛不住。我这边用了带磁盘缓存的图片管线，配合cached_network_image的思路，但有一点要注意：在鸿蒙上第三方图片加载插件支持不统一。遇到不兼容的情况，最稳妥的方案是自己封装一层图片加载：

class CoverImage extends StatelessWidget { final String url; final double width; final double height; @override Widget build(BuildContext context) { return Image.network( url, width: width, height: height, fit: BoxFit.cover, errorBuilder: (_, __, ___) => _buildPlaceholder(context), loadingBuilder: (context, child, progress) => progress == null ? child : const Center(child: CircularProgressIndicator()), ); } }

实际项目中我还在外层包了一个基于文件缓存的封装，判断条件是“本地存在同名哈希文件就直接走 FileImage，否则走网络”。这个方案在 Android、iOS、鸿蒙三端表现一致，而且几乎不依赖平台插件。

4.3 下拉刷新与加载更多

书城列表的刷新用 Flutter 自带的RefreshIndicator就够了，但加载更多这里有个坑：阅读器的列表滚动和加载更多很容易互相干扰，尤其是在翻页或快速滚动时，如果同时加载多页数据，列表会出现跳动。我的经验是给分页加载加一个互斥锁：

bool _loadingMore = false; Future<void> _loadMore() async { if (_loadingMore) return; _loadingMore = true; try { final next = await _fetchNextPage(); if (next.isEmpty) { _hasMore = false; } else { _items.addAll(next); } } finally { _loadingMore = false; } }

这个写法看起来简单，但能避免 90% 的分页重复请求问题。

5. 阅读器核心：正文分页与翻页手势

5.1 用 TextPainter 做分页：为什么不能按字数硬切

在线小说阅读器最核心的一块，就是正文分页。

很多人第一反应是“每页 500 字，第一章 5000 字，切 10 页”。真这么做的后果是：中英文混排、标点挤压、行尾对齐、段落缩进之后，每页实际显示的字数并不一样，而且换字号之后整本书的页数全乱套。

正确做法是用TextPainter拿到实际排版结果，再按容器高度切页。核心思路是：给定页面宽度、高度和 TextStyle，把整章文本按段落拆分后逐个“排版进去”，当累积高度超过容器高度时，当前累积的文本就是一页。

List<String> paginateChapter({ required String text, required double pageWidth, required double pageHeight, required TextStyle style, }) { final pages = <String>[]; final paragraphs = text.split('\n'); final currentPage = StringBuffer(); var currentHeight = 0.0; TextPainter measure(String content) { final tp = TextPainter( text: TextSpan(text: content, style: style), textDirection: TextDirection.ltr, )..layout(maxWidth: pageWidth); return tp; } for (final para in paragraphs) { final withPara = para.isEmpty ? '\n' : '$para\n'; final test = currentPage.toString() + withPara; final tp = measure(test); if (currentHeight + (tp.height - currentHeight) <= pageHeight) { currentPage.write(withPara); currentHeight = tp.height; } else { if (currentPage.isNotEmpty) { pages.add(currentPage.toString()); } currentPage.clear(); currentPage.write(withPara); currentHeight = measure(withPara).height; } } if (currentPage.isNotEmpty) { pages.add(currentPage.toString()); } return pages; }

这段代码是简化版本，真实项目里还要处理段落间距、段首缩进、首行悬挂标点等细节。但你已经可以看到核心逻辑：不是数字数，而是让排版本身告诉我们一页能放多少内容。

5.2 翻页方案：PageView 还是自定义手势

分页算法跑通之后，翻页交互有两条路线：

一条是PageView.builder，每页放一个Text。优点是实现快，横向滑动手感天然流畅；缺点是你想要“仿真翻页”或“覆盖翻页”效果时，自由度不够。

另一条是自己管理页索引和手势，用GestureDetector监听点击区域来翻页。小说阅读器的实际用户习惯其实很简单：点击右侧翻下一页，点击左侧翻上一页，点击中间弹出菜单。

我最后选择的是混合做法：正文区用 PageView，点击区域处理用透明的 GestureDetector 盖在上面。菜单弹出用 Overlay 实现，不打断阅读器的页面状态。

5.3 字号、行距、背景与夜间模式

阅读器的设置项会直接影响分页结果。每一次字号变化，都要重新调用分页算法，如果章节很长（超过 10 万字），分页会有几十毫秒的耗时。我的优化方案是：把分页结果缓存起来，key 是“章节ID + 字号 + 行距 + 页面尺寸”，用户设置变化时只重新分当前章节，后台异步把整书分页缓存刷新。实测下来，用户连续调整字号时不会出现明显的卡顿。

夜间模式我推荐用主题层解决，而不是给每一页单独传颜色。在 MaterialApp 的 theme 里根据当前模式切换scaffoldBackgroundColor和文字颜色，阅读器里的所有组件自动跟随，避免某个页面漏改导致夜间模式下白底刺眼。

5.4 进度记录与章节跳转

进度记录的最小单位是“章节 + 章节内字符位置”。每次翻页时，把当前页的第一个字符在全章中的偏移量记下来。这样用户退出再进入，可以精确恢复到离开时看到的那一页，而不是每次都回到章节开头。

我用的实现是：分页时每一页额外保存startOffset和endOffset：

class PageInfo { final String content; final int startOffset; final int endOffset; }

读进度时先根据charPosition找到startOffset <= charPosition < endOffset的页码，直接打开那一页。比用章节号 + 页号记录更稳，因为页号会随字号设置变化，而字符偏移量是稳定的。

6. 网络层、缓存与离线阅读的工程化实现

6.1 Dio 封装与超时策略

网络层我用 Dio 做统一封装。在线小说阅读器的接口有一个特点：书城列表可以接受稍慢的加载，但章节内容的请求必须快，而且失败要能快速重试。所以我在封装里做了两套配置：

• 书城接口：连接超时 10 秒，接收超时 15 秒；
• 章节接口：连接超时 5 秒，接收超时 10 秒，失败重试 2 次。

章节内容属于“失败一次用户就明显烦躁”的类型，重试策略必须带上。另外要强调一点：不要用默认 User-Agent 去请求小说内容接口。很多内容源对异常 UA 的风控很敏感，我是在拦截器里统一设置了一个看起来像普通浏览器的 UA，实测请求成功率明显提升。

6.2 章节缓存与本地续读

离线阅读是小说阅读器区别于普通浏览器的核心能力。章节缓存我按“书籍 ID / 章节索引”作为 key，正文内容以字符串形式存储在本地数据库。缓存的读取路径是：

• 用户打开章节时，先查本地缓存；
• 有缓存且未过期，直接展示；
• 没有缓存，走网络请求；
• 网络请求成功后，先写缓存再渲染；
• 如果网络失败且本地有旧缓存，则降级展示旧缓存并提示“内容可能不是最新”。

这套逻辑保证了弱网环境下用户永远能看到内容，而不是看到转圈加载失败。

6.3 预取策略与流量控制

阅读器还有一个细节功能：后台预取。很多人看小说时是连续翻页的，如果每翻一页才发起一次网络请求，体验肯定不行。我在阅读器启动后，会预取当前章节之后 3 章的内容；用户连续翻页超过 5 章后，再继续预取后续章节。

预取不能无限并发，我在代码里维护了一个最多同时 2 个请求的队列。如果用户快速连翻，预取任务全部堆积，容易把网络打满，也会被内容源限流。所以队列里加了一个优先级：离当前阅读位置越近的章节越优先。

6.4 缓存淘汰

缓存不能无限膨胀。我给本地缓存设置了一个上限，超过 200 章或总大小超过 300MB 时，按最近阅读时间倒序淘汰最久未读的章节。这个策略在用户阅读很多本书时尤其重要，避免书架里有几百本书、缓存占满存储的情况发生。

淘汰逻辑放在每次章节缓存写入后触发，异步执行，不阻塞阅读流程。

7. 鸿蒙真机调试与上架前的现实问题

7.1 连接设备与日志查看

鸿蒙真机调试和 Android 很像，但命令工具链不同。先在开发者选项里开启 USB 调试，连接后用hdc list targets查看设备是否识别。日常看日志用的是hdc hilog，和adb logcat流程接近。

如果你遇到设备识别不到，优先检查 hdc 服务的进程是否匹配当前设备版本。我遇到过换了一台手机后 hdc 服务一直连接失败，重启 hdc 服务就好了：

hdc kill hdc start

7.2 权限配置与行为差异

鸿蒙上最容易踩的坑是权限。小说阅读器最常用的网络权限在鸿蒙侧配置文件和 Android 侧完全不同，前面提到过这点，但真机调试时它带来的现象很有意思：Android 上网络权限缺失会在应用启动时立刻崩溃，鸿蒙上则是静默失败，表现为接口请求一直超时或返回失败码。遇到这种问题不要只查网络代码，先看权限声明。

另外存储权限在鸿蒙上的策略和 Android 也不太一样。小说阅读器的离线缓存如果走应用私有目录，基本不需要额外申请权限；如果要把缓存导出到公共目录，就要单独处理。

7.3 插件不兼容时的兜底方案

阅读器项目里如果用到了高德定位、分享、推送这类第三方插件，大概率会遇到鸿蒙没有对应实现的情况。我的处理原则是“能绕就绕，绕不过就抽离”。

以 Toast 为例，很多 Flutter 插件在鸿蒙上不提供原生实现，最简单的兜底是用 Flutter 自带的SnackBar替代。这个改动不涉及业务逻辑，只是一个展示组件的替换。再比如本地通知，如果插件不支持鸿蒙，就先砍掉这个功能，用站内信提示代替，保证主流程不受影响。

7.4 性能表现与发热控制

在线小说阅读器在鸿蒙真机上跑起来后，我重点观察了两个指标：翻页帧率和长时间阅读的发热情况。

翻页这一块，Flutter 在鸿蒙上的表现超出我的预期。用 profile 模式跑，翻页和分页过程基本稳定在 50~60 帧，没有出现明显掉帧。发热方面，真正的瓶颈反而不在 Flutter 引擎，而是预取线程和数据库写入。预取章节时如果网络快、内容大，连续写入缓存会让设备背部升温。我的优化方案是：把缓存写入改成批量事务，每 3 章合并提交一次，同时降低预取的触发频率。

7.5 上架前提醒

最后提醒一句：鸿蒙应用的上架审核对“应用自述”要求比较细。小说阅读器如果涉及在线内容，需要在应用描述里如实写明内容来源和版权处理方式，不要等审核被拒了再补材料。另外建议提前申请开发者实名认证，越早越好，因为审核周期里有实名信息的校验环节，卡在认证上非常不划算。

我在整个项目里最深的体会是：跨平台不是“写一次跑所有端”的童话，而是“逻辑写一次，适配每个端”的工程过程。Flutter 把 UI 和业务逻辑的复用做到了极致，鸿蒙适配分支又把最后一段路补上了。但真正决定项目能不能落地的，还是你在分页算法、缓存策略和平台差异上愿不愿意下功夫。希望这篇记录能让你在动手做 Flutter 鸿蒙项目时少走几步弯路。