企业官网建设流程全解析

手机上看漫画，很多人并不缺一个能装漫画的 App，缺的是清爽的阅读体验。官方客户端往往包含登录态、会员、插屏广告，不同平台之间的内容又互相隔离，用户很容易把注意力花在账号和提醒上。搜索引擎里经常出现的“免费、无广告、免登录、全网聚合”类漫画阅读 APP，多数是包壳或版权风险极高的第三方整合版，装上之后能看多久、数据是否安全都很难保证。与其长期依赖这类来路不明的工具，不如换一个思路：按“本地书架 + 可配置书源 + 漫画阅读器渲染层”的方式，自己实现一款免登录、无内置广告、界面干净的漫画阅读 APP 原型。这篇内容会从一个最小可运行的 Android 项目讲起，把漫画阅读 APP 的架构边界、存储设计、网络来源抽象、图片渲染优化等关键点解释清楚。这里不提供任何盗版资源聚合方案，只讨论如何在版权合规的前提下，把工程能力做到干净、可靠、可扩展。

本文字量较大，前置知识要求是熟悉 Kotlin 基础语法、Android 四大组件基本使用，并且至少能创建一个 Compose 空项目。如果你已经写过一些 Android 界面，只是还没有把“书架、书源、阅读器、缓存”这些模块串起来，那这篇会比较合适。

1. 先别急着写代码，把漫画阅读 App 的真实结构拆开

漫画类应用的难点从来不是“显示一张图片”，而是如何处理好局部缓存、阅读进度、来源差异、翻页手感、大图内存控制等一连串问题。只有先理解整体模块，再开始编码，后面每一步才不会被细节带偏。

1.1 漫画阅读 App 不只是图片浏览器

从功能层面看，一个完整的漫画阅读 App 至少包含五层模块：

很多初级项目把所有逻辑都写在 Activity 和 Adapter 里，短时间能跑起来，一旦需要支持第二个书源，代码会非常难维护。原因就是来源解析和书架存储耦合得太紧。正确做法是把每一层拆开，让上层界面只依赖抽象接口，不关心数据来自本地 ZIP、远程 JSON 还是某个网站的 HTML 页面。

1.2 “免费、无广告、免登录”对应哪些工程决策

标题中常出现的这几个词，并不只是一个营销包装，它们分别对应一组工程决策：

• 免费：应用本身可以不上架收费分销渠道，也可以做成开源项目或本地工具。
• 无广告：启动时不加载第三方广告 SDK，不申请读取广告标识符，页面里不插入开屏、插屏广告。
• 免登录：不引入账号体系，所有书架和进度都保存在本地数据库中，不需要手机号、不需要第三方授权。
• 画质超清：图片不做强制压缩，阅读器支持原图加载、双指缩放、双页模式。

这些需求本身是正当的。很多第三方打包 App 的问题不在于“免费”或“无广告”，而在于把未授权内容嵌进应用，同时内置统计和推送 SDK，用户根本不知道数据去了哪里。自己做阅读器时，完全可以保留“无登录、无广告、本地优先”的产品形态，但内容来源必须由使用者自己确认并承担相应义务。

1.3 为什么把“全网聚合”做成统一模型而不是内置固定源

如果直接把某个网站写在 Activity 中，最快一天就能出效果。问题在于来源网址一旦改版、封 IP、关站或修改参数，代码就立刻失效。对普通用户来说，第三方“聚合版”随时会崩，原因就在这里。

更可靠的做法是定义一套来源抽象：

interface MangaSource { val id: String suspend fun search(keyword: String): List<ComicMeta> suspend fun loadChapters(comicId: String): List<Chapter> suspend fun loadChapterImages(comicId: String, chapterId: String): List<ChapterImage> }

界面只需要面向MangaSource编程。新增来源时，只要新增一个实现类，并在设置页里让用户配置来源信息即可。这里特别要强调：实际项目中，用户添加的任何来源都必须确认其内容有合法授权。文章不提供任何用于抓取未授权站点的解析模板。

2. 环境准备与项目骨架

技术文章最怕环境不一致导致示例跑不起来。下面以我写本文时使用的版本为例，实际操作时建议先打开 Android Studio 看一下自己默认生成的版本，再决定是否修改。

2.1 开发环境版本建议

下表用于快速对照，不建议把某个版本当成不可变的唯一标准。创建新项目时，Android Studio 自动生成的依赖版本往往更可靠。

2.2 创建空白 Compose 工程并加入依赖

新建项目时选择 “Empty Activity”，模板启用后，在app/build.gradle.kts中追加关键插件和依赖。

plugins { id("com.android.application") id("org.jetbrains.kotlin.android") id("org.jetbrains.kotlin.plugin.serialization") version "2.0.21" id("com.google.devtools.ksp") version "2.0.21-1.0.27" } android { namespace = "com.example.comicreader" compileSdk = 35 defaultConfig { applicationId = "com.example.comicreader" minSdk = 23 targetSdk = 35 versionCode = 1 versionName = "1.0" } buildFeatures { compose = true } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } } dependencies { implementation(platform("androidx.compose:compose-bom:2024.12.01")) implementation("androidx.compose.ui:ui") implementation("androidx.compose.material3:material3") implementation("androidx.activity:activity-compose:1.9.3") implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.7") implementation("androidx.room:room-runtime:2.6.1") implementation("androidx.room:room-ktx:2.6.1") ksp("androidx.room:room-compiler:2.6.1") implementation("com.squareup.okhttp3:okhttp:4.12.0") implementation("io.coil-kt:coil-compose:2.7.0") implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3") }

注意：如果项目使用 Java 17，Room 的 KSP 注解处理器版本必须与 Kotlin 版本匹配。Kotlin 升级后，KSP 版本也要同步升级，否则会直接编译报错。

2.3 AndroidManifest 与网络明文策略

漫画阅读器必然需要网络权限和本地文件访问权限。最稳妥的方式是使用系统文件选择器，不申请整个存储空间的读取权限。

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

AndroidManifest.xml中 application 节点内建议加入网络明文判断：

<application android:allowBackup="true" android:usesCleartextTraffic="false" android:theme="@style/Theme.ComicReader"> <activity android:name=".MainActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application>

实际开发中，本地局域网书源或测试服务器可能使用http://地址。Android 9 开始默认禁止明文请求。如果只是本地联调，可以把android:usesCleartextTraffic临时设为true。生产环境不应该全局打开，建议使用network_security_config.xml缩小范围，只允许特定域名走明文。

注意：不要为了省事把网络限制全部关掉再上架。全局明文流量不仅影响安全性，也会在应用市场审核时成为明显问题。

3. 书架设计：本地优先、免登录的数据底座

免登录不代表没有数据模型。相反，书架是漫画 App 所有功能的入口。把书架的数据结构设计好，以后无论接入多少个来源，阅读进度和收藏历史都能稳定工作。

3.1 用 Room 保存漫画、章节和阅读进度

推荐把实体拆成三张表：漫画表保存来源信息和封面，章节表保存某一部作品下的所有章节，阅读进度表保存最近阅读位置。

@Entity( tableName = "comics", primaryKeys = ["sourceId", "comicId"] ) data class ComicEntity( val sourceId: String, val comicId: String, val title: String, val author: String = "", val coverUrl: String = "", val intro: String = "", val lastChapterTitle: String = "", val updatedAt: Long = System.currentTimeMillis() ) @Entity( tableName = "chapters", primaryKeys = ["sourceId", "comicId", "chapterId"] ) data class ChapterEntity( val sourceId: String, val comicId: String, val chapterId: String, val title: String, val order: Int, val updatedAt: Long = System.currentTimeMillis() ) @Entity(tableName = "reading_progress") data class ReadingProgressEntity( @PrimaryKey val compositeId: String, val sourceId: String, val comicId: String, val chapterId: String, val pageIndex: Int = 0, val updatedAt: Long = System.currentTimeMillis() )

用sourceId + comicId作为联合主键，是为了避免不同来源出现相同 ID 时互相覆盖。阅读进度表里的compositeId可以用"$sourceId/$comicId"拼出来，这样每次读取进度时不需要走复合查询。

有两点需要关注：

• updatedAt用于书架排序，用户最近打开的漫画排在最前面。
• ChapterEntity.order必须使用稳定的整数排序。很多来源的章节名是“第1话”“第10话”，直接按字符串排序会出现“第10话”排在“第2话”前面的问题。

3.2 用 Flow 驱动书架 UI

Room 天然支持返回Flow<List<T>>。书架 UI 只要收集这个 Flow，数据库变化后界面会自动刷新。

@Dao interface ComicDao { @Insert(onConflict = OnConflictStrategy.REPLACE) suspend fun upsertComic(comic: ComicEntity) @Insert(onConflict = OnConflictStrategy.REPLACE) suspend fun upsertChapters(chapters: List<ChapterEntity>) @Query( """ SELECT * FROM comics ORDER BY updatedAt DESC """ ) fun observeAllComics(): Flow<List<ComicEntity>> @Query( """ SELECT * FROM chapters WHERE sourceId = :sourceId AND comicId = :comicId ORDER BY `order` ASC """ ) fun observeChapters(sourceId: String, comicId: String): Flow<List<ChapterEntity>> @Query( """ SELECT * FROM reading_progress WHERE compositeId = :compositeId """ ) fun observeProgress(compositeId: String): Flow<ReadingProgressEntity?> }

免登录的架构下，书架数据默认只存在于应用私有目录。即使不采集用户信息，也要在 UI 上提供备份和导出入口，否则用户换手机就丢失全部阅读记录。

3.3 导入本地 CBZ 或 ZIP 文件

CBZ 是漫画领域常见打包格式，本质是一个 ZIP 压缩包，里面按顺序存放图片。Android 端不需要额外引第三方库，直接用java.util.zip.ZipFile就可以。

fun listImagesFromCbz(zipFile: File): List<ZipEntry> { return ZipFile(zipFile).use { zip -> zip.entries() .asSequence() .filter { !it.isDirectory } .filter { entry -> val name = entry.name.lowercase() name.endsWith(".jpg") || name.endsWith(".jpeg") || name.endsWith(".png") || name.endsWith(".webp") } .sortedBy { it.name } .toList() } }

这里有一个容易被忽略的坑：ZIP 中文件名可能包含../或绝对路径。如果直接把 entry 名称拼到输出目录后解压，会造成路径穿越。安全做法是把 entry 名称归一化，去掉路径分隔符，只取文件名，并拒绝包含..的条目。

fun safeExtractEntryName(entry: ZipEntry): String? { val rawName = entry.name.replace("\\", "/") if (rawName.startsWith("/") || rawName.contains("..")) { return null } return rawName.substringAfterLast("/") }

用系统文件选择器选择 CBZ 文件时，建议把文件复制到应用私有缓存目录再做解压或读取。不要长期持有content://的内容流，因为部分文件管理器的授权访问可能在应用重启后失效。

4. 把书源做成一等公民：来源抽象与配置化

真正的漫画阅读器很难只依赖一个来源。目录接口、封面字段、章节列表、图片地址格式都不一样。最直接的错误做法是在页面里写死“来源 A 的请求逻辑”。一旦接入来源 B，整个页面都要跟着改。

4.1 设计统一的元数据模型

在来源抽象层之上，定义一套统一的漫画元数据和章节数据模型：

@Serializable data class ComicMeta( val sourceId: String, val comicId: String, val title: String, val author: String = "", val coverUrl: String = "", val intro: String = "" ) @Serializable data class Chapter( val comicId: String, val chapterId: String, val title: String, val order: Int ) @Serializable data class ChapterImage( val chapterId: String, val pageIndex: Int, val imageUrl: String )

有了这套模型后，所有来源解析结果最终都要转换成上面三种对象。这样书架、阅读器、缓存模块就能完全忽略来源差异。

4.2 定义一个演示用的 JSON 书源配置

为了让示例可运行，不需要抓取任何真实网站，可以使用一个本地 Mock 服务或自建授权服务。先定义来源配置结构：

@Serializable data class JsonSourceConfig( val id: String, val name: String, val baseUrl: String = "", val searchPath: String = "/search?q={keyword}", val chapterPath: String = "/comic/{comicId}/chapters", val imagePath: String = "/chapter/{comicId}/{chapterId}/images" )

对应的请求返回 JSON 可以自行规范。以搜索接口为例，统一约定返回结构：

{ "code": 0, "message": "ok", "data": { "items": [ { "id": "demo-001", "title": "示例漫画 001", "author": "作者A", "cover": "https://example.com/covers/001.jpg", "intro": "这是一本示例漫画" } ] } }

解析这一结构的 Kotlin 代码可以用kotlinx.serialization，也可以用标准库中的org.json.JSONObject。对小型阅读器项目来说，JSON 结构不复杂时，JSONObject反而更直观。

suspend fun parseSearchResult(sourceId: String, raw: String): List<ComicMeta> { return withContext(Dispatchers.IO) { val root = JSONObject(raw) if (root.optInt("code", -1) != 0) { error("搜索接口异常: ${root.optString("message")}") } val items = root.getJSONObject("data").getJSONArray("items") buildList { repeat(items.length()) { index -> val item = items.getJSONObject(index) add( ComicMeta( sourceId = sourceId, comicId = item.getString("id"), title = item.getString("title"), author = item.optString("author", ""), coverUrl = item.optString("cover", ""), intro = item.optString("intro", "") ) ) } } } }

JSONObject的好处是修改字段不影响编译，缺点是缺少编译期类型检查。如果接口字段经常变化，建议最终切换成kotlinx.serialization的@Serializable数据类并用Json { ignoreUnknownKeys = true }解析。

4.3 网络请求层封装

网络请求层要做三件事：拼接 URL、发起 GET 请求、读取字符串响应。真正的工程还要加超时、重试、日志和异常包装。

class HttpBookClient( private val client: OkHttpClient, private val connectTimeoutSeconds: Long = 10, private val readTimeoutSeconds: Long = 15 ) { private val httpClient: OkHttpClient = client.newBuilder() .connectTimeout(connectTimeoutSeconds, TimeUnit.SECONDS) .readTimeout(readTimeoutSeconds, TimeUnit.SECONDS) .build() suspend fun getJson(url: String): String = withContext(Dispatchers.IO) { val request = Request.Builder() .url(url) .header("User-Agent", "ComicReaderSample/1.0") .build() httpClient.newCall(request).execute().use { response -> if (!response.isSuccessful) { error("HTTP ${response.code}: $url") } response.body?.string() ?: error("response body empty") } } }

将withContext(Dispatchers.IO)放在网络层内部，可以保证调用方即使从 UI 线程调用，也不会直接卡 UI。不过更推荐在 ViewModel 中使用协程调用网络层，让网络调度和生命周期解耦。

4.4 使用 ViewModel 组织搜索流程

一个简单但规范的流程是：用户在搜索框输入关键字，ViewModel 调用search，UI 观察StateFlow。

class SearchViewModel( private val source: MangaSource ) : ViewModel() { private val _uiState = MutableStateFlow<SearchUiState>(SearchUiState.Idle) val uiState: StateFlow<SearchUiState> = _uiState.asStateFlow() fun search(keyword: String) { viewModelScope.launch { _uiState.value = SearchUiState.Loading _uiState.value = try { val result = source.search(keyword) SearchUiState.Success(result) } catch (e: Exception) { SearchUiState.Error(e.message ?: "unknown error") } } } } sealed interface SearchUiState { data object Idle : SearchUiState data object Loading : SearchUiState data class Success(val comics: List<ComicMeta>) : SearchUiState data class Error(val message: String) : SearchUiState }

这种封装看起来多写了几行代码，但对排查问题帮助很大。把 Loading、Success、Error 三种状态显式建模后，界面不会出现“搜索失败但页面空白”的尴尬情况。

5. 漫画阅读器渲染层：页面容器、缩放与缓存策略

书架和来源只是把数据送到门口，真正决定用户体验的，是打开章节后图片如何展示、如何翻页、如何缓存。

5.1 单页翻页/横向翻页选择哪种容器

漫画阅读常见有两种主模式：

• 日漫风格：从右往左或从左往右单页翻页，适合横屏阅读。
• Webtoon 风格：纵向连续滑动，适合手机竖屏阅读长条图。

在 Compose 中，横向分页可以直接使用HorizontalPager，纵向阅读可以直接使用LazyColumn。下面以横向分页为例：

@Composable fun MangaPager( pages: List<ChapterImage>, initialPage: Int, modifier: Modifier = Modifier ) { val pagerState = rememberPagerState( initialPage = initialPage, pageCount = { pages.size } ) HorizontalPager( state = pagerState, modifier = modifier.fillMaxSize() ) { pageIndex -> val imageUrl = pages[pageIndex].imageUrl MangaPageView(imageUrl = imageUrl) } }

这里的关键点是把ChapterImage中的pageIndex与PagerState.currentPage对应起来。不要依赖列表元素的角标去恢复阅读位置，应该直接把pageIndex保存到 Room，下次进入时用rememberPagerState(initialPage = savedPage)定位。

5.2 图片缩放与手势冲突处理

漫画大图常需要双指缩放。必须避免缩放手势和翻页手势互相打架，否则用户会非常痛苦。

@Composable fun MangaPageView( imageUrl: String, modifier: Modifier = Modifier ) { var scale by remember { mutableStateOf(1f) } var offset by remember { mutableStateOf(Offset.Zero) } val context = LocalContext.current AsyncImage( model = ImageRequest.Builder(context) .data(imageUrl) .crossfade(true) .build(), contentDescription = null, contentScale = ContentScale.Fit, modifier = modifier .fillMaxSize() .pointerInput(Unit) { detectTransformGestures { _, pan, zoom, _ -> val newScale = (scale * zoom).coerceIn(1f, 5f) scale = newScale offset = pan } } .graphicsLayer { scaleX = scale scaleY = scale translationX = offset.x translationY = offset.y } ) }

这个实现只是最小示例，实际项目还需要：

• 当缩放倍数等于 1 时，把 offset 重置为零。
• 当缩放倍数大于 1 时，禁止 Pager 拦截左右滑动。
• 双页模式下，左右两页各自维护独立的缩放状态。
• 处理旋转屏幕或切换全屏时的状态恢复。

比较常见的处理方式是监听pagerState的拖拽事件，在图片scale > 1f时不做翻页；在图片scale == 1f时把翻页事件交还给 Pager。可以用pointerInput的awaitEachGesture手写事件分发，也可以根据场景选择缩放和翻页的手势优先级。

5.3 大图内存与磁盘缓存策略

漫画图片通常比普通列表封面大很多。如果不加限制地把图片塞进内存，低端机很容易 OOM。Coil 默认会按照目标 View 尺寸加载裁剪后的图片，但如果页面容器是全屏，仍需关注单张图片的内存占用。

建议统一设置一个 Coil 的ImageLoader：

val imageLoader = ImageLoader.Builder(context) .memoryCachePolicy(CachePolicy.ENABLED) .diskCachePolicy(CachePolicy.ENABLED) .crossfade(false) .respectCacheHeaders(false) .build() CompositionLocalProvider( LocalImageLoader provides imageLoader ) { AppContent() }

respectCacheHeaders(false)对漫画阅读器比较友好，因为不少图片服务器没有返回正确的缓存响应头。Coil 默认会根据 HTTP 缓存头决定是否复用磁盘缓存，关闭该选项后可以明显提高重复阅读时的加载速度。

注意：不要为了“看得更清”就无条件用ImageRequest.size(Size.ORIGINAL)加载原图。超大长图建议使用专业的大图缩放控件，或把图片切成瓦片加载。普通页面原图配合ContentScale.Fit可以满足大多数场景。

6. 免登录不等于不做数据安全与备份

很多漫画聚合工具强调“免登录”是为了降低用户使用门槛。但从工程角度，应用不登录时更容易出现问题：用户不知道数据存在哪里，也没有任何服务端账号可恢复。对自研阅读器来说，免登录只意味着不引入账号体系，不影响应用做本地备份、导出、加密和恢复。

6.1 本地数据的安全边界

Room 数据库默认保存在应用私有目录，其他应用无法直接读取。但这并不代表完全没有风险。

• 设备 root 后，应用私有目录可能被读取。
• android:allowBackup="true"时，系统备份工具会把数据库和缓存一并备份。
• 日志中不要打印完整请求路径或用户搜索记录。

如果后续要保存本地账号 Token 或加密书源配置，建议使用 Android Keystore 或引入 SQLCipher。至少在文档和设置页写明：书架数据保存在本机，不会上传到任意服务器。

6.2 书架备份与导出的实现思路

哪怕不登录，也可以提供一个“生成备份文件”的功能。备份内容一般包含书架信息和阅读进度，不包括已加载的图片缓存。

{ "export_version": 1, "export_time": 1735689600000, "comics": [ { "sourceId": "demo-json", "comicId": "demo-001", "title": "示例漫画 001", "lastChapterTitle": "第1话" } ], "progress": [ { "compositeId": "demo-json/demo-001", "chapterId": "c1", "pageIndex": 5 } ] }

导入时先校验export_version和字段完整性，再分批写入 Room。因为导入过程可能涉及大量数据，建议在后台协程中执行，并显示进度条。

6.3 本地工具同样要守住内容边界

免登录、无广告、本地优先，这些产品特点都不等于可以绕过内容授权。技术上可以解析很多网页，但把未授权作品提供给公众访问，属于明确的版权风险。自用阅读器使用有授权的测试源，或导入自己制作的图片打包文件，是更稳妥的练习路径。

开发者的合理做法是：

• 在应用内提供“添加来源”设置，但来源列表不预置任何未授权站点。
• 对搜索结果增加来源标识。
• 在 README 或用户协议中明确内容责任归属。
• 发布到应用市场前，确认自己没有通过应用分发盗版内容。

7. 完整运行：从本地 CBZ 到网络书源的验证链路

把模块拆完后，需要有一个最小闭环能够判断工程是否正确。这里建议分两步验证：先跑通本地 CBZ，再跑通远程 JSON 书源。

7.1 准备一个测试用 CBZ 文件

在电脑上准备一个测试目录，放入四张图片，然后打成 ZIP 并重命名为.cbz。

mkdir -p /tmp/comic_sample cp page_01.jpg /tmp/comic_sample/001.jpg cp page_02.jpg /tmp/comic_sample/002.jpg cp page_03.jpg /tmp/comic_sample/003.jpg cd /tmp/comic_sample zip -r ../comic_sample.cbz .

Android 端点击“导入本地文件”时，使用系统OpenDocument文件选择器选择这个 CBZ 文件。导入成功后书架应出现封面和标题，如果无法识别，需要检查文件名结构是否符合常见 CBZ 规范。

7.2 启动本地 Mock JSON 书源

网络书源验证不需要真实网站。可以在电脑上启动一个简单的 JSON 服务：

from flask import Flask, jsonify app = Flask(__name__) @app.route("/search") def search(): return jsonify({ "code": 0, "message": "ok", "data": { "items": [ {"id": "demo-001", "title": "示例漫画", "author": "demo", "cover": "http://10.0.2.2:8080/cover.jpg", "intro": "demo"} ] } }) if __name__ == "__main__": app.run(host="0.0.0.0", port=8080)

Android 模拟器访问宿主机使用的是10.0.2.2，不是127.0.0.1。真机调试需要把地址改成电脑的局域网 IP，并确保同一 Wi-Fi 下防火墙允许访问 8080 端口。

7.3 验证搜索、章节加载和阅读进度恢复

验证时要关注的不是“能不能打开”，而是数据流转是否完整。建议按照以下链路检查：

1. 搜索关键字，确认ComicMeta列表正确展示。
2. 点击漫画进入详情页，确认章节列表按order排序。
3. 点击某一章节，确认图片 URL 列表返回正确。
4. 翻到第 3 页后退出，再次进入同一章节，确认能恢复到第 3 页。
5. 杀掉应用进程后再次启动，确认书架排序仍正常。

第 4、5 步最容易出问题。因为PagerState恢复通常只在内存中，如果页面不读取 Room 中的进度，或进度表没有在退出时写入，重启后就丢位置。

8. 常见问题排查：现象、原因与处理顺序

独立实现阅读器时，很大一部分时间会花在排查和适配问题上。下面整理实际开发中最常见的几类问题。

8.1 本地 CBZ 导入后空白或乱码

推荐做法：本地 CBZ 导入只保留图片文件名和排序信息，不把整包内容长期保留在应用私有存储中。书架数据库只保存 JSON 元数据，阅读时再从原文件读取。

8.2 图片加载为空或直接失败

常见现象是图片加载一直转圈，或出现灰屏。排查顺序应该是：

1. 先用系统浏览器打开图片 URL，确认地址能访问。
2. 检查应用是否有INTERNET权限。
3. 如果地址是http://，检查usesCleartextTraffic是否允许明文。
4. 如果地址需要Referer，Coil 请求时没有带对应请求头，图片服务器可能拒绝。
5. 查看 Logcat 里 Coil 是否有 404、403 或 DNS 错误日志。

对需要校验来源的图片服务器，可以在ImageRequest中增加请求头。但要注意，把某种来源的 Referer 写死在页面层，会让阅读器失去通用性。更合理的方式是在书源配置中同步配置图片请求头。

8.3 书源解析不生效

如果搜索返回了 JSON 但没有漫画条目，优先检查接口返回的实际内容和代码中解析字段是否一致。

不要一上来就怀疑代码。多数解析问题都来自接口字段变化或请求 URL 拼接错误。排查时先打印原始响应，再结合响应改代码，效率最高。

9. 生产化落地要考虑的细节与扩展方向

一个能在自己手机上跑通的阅读器 Demo，距离一个能发布的应用还有很长的路。越往后，越需要关注下面这些工程细节。

9.1 发布前必做的检查清单

下面的清单适合在准备正式版本前逐项确认：

• [ ] 是否移除了开发用日志中的 Token、Cookie 等敏感信息。
• [ ] 是否确认所有来源均有合法授权，并明确内容责任。
• [ ] 是否处理了无网络、弱网、超时、接口异常分支。
• [ ] 是否设置了 Coil 磁盘缓存上限，并允许用户清空缓存。
• [ ] 是否检查了 Android 12+ 导出组件配置。
• [ ] 是否符合 targetSdk 对明文流量、通知权限、文件访问的要求。
• [ ] 是否准备了解析源升级方案，来源地址可配置化。
• [ ] 是否支持书架备份和恢复。
• [ ] 是否对超大图做了采样或分块加载。
• [ ] 是否用低端机验证过 OOM 与卡顿。

这份清单并不是模板，而是阅读器项目最容易遗漏的十个点。实际发布前还需要结合自己的包体、隐私政策、用户协议单独确认。

9.2 从本地工具走向正式产品的扩展方向

如果要把这个项目继续扩大，比较合理的扩展方向包括：

• 支持 WebDAV 同步书架和阅读进度