企业官网建设流程全解析

• 移动开发
• 桌面应用
• 音视频
• 视频

Love Iwara（代号i_iwara/2i）是一个基于 Flutter 构建的第三方 Iwara 客户端，以单一代码库覆盖 Android、Meta Quest（Horizon OS）、Windows、macOS、Linux 与 iOS 六大平台。本文以仓库官方俄语版 README（docs/readme/README_RU.md）为主体，结合源码与构建配置，系统拆解其平台架构、Meta Quest 空间化体验、双 flavor 构建体系、Android 签名流程，以及最具特色的多语言标签本地化工程。读完你将掌握：如何从零搭建环境并产出各平台 Release 包、如何配置 Android 签名与 CI 密钥、理解 Iwara/Oreno3d 标签词库从 AI 翻译到 CDN 热更新的完整链路，以及 12 门界面语言背后的设计与回退规则。

项目定位与平台支持

Love Iwara 的目标是在手机、平板与桌面设备上提供「流畅、接近原生」的 Iwara 浏览体验，全部来自一套代码库。官方文档明确声明了三项使用边界：

• 项目始于作者学习 Flutter 的练手之作，部分代码可能不够精致，但持续维护、功能丰富；
• 仅用于学习与个人参考，不建议用于生产环境，且禁止在任何公开平台推广该项目；
• 开发者与 Iwara 及其内容供应商没有任何关联，应用自身不托管任何内容。

平台支持矩阵如下（对应 README 原表）：

¹ Quest 构建是面向 Horizon OS（Android 14+）的独立 arm64 APK，携带 Meta Spatial SDK；普通 Android APK 不受影响，仍支持 Android 7.0+（minSdk 24）。² Linux 构建会产出，但当前因缺少测试设备尚未实测。

核心功能全景

视频播放

• 基于media_kit（libmpv）的流畅播放，支持画质选择、倍速控制（含默认/自动速度）与全屏；
• 进度条悬停与拖拽时显示预览缩略图；
• 描述与评论中的可点击时间戳可直接跳转；
• 「继续观看」抽屉，可选进入视频后自动续播；
• 实时下载速度指示；
• 平面屏幕上的全景观看：VR180 / 360° 文件在普通播放器中会显示为两片被压扁的半图，这里会呈现正确比例的可拖拽视口。由于 Iwara 文件完全不携带球面元数据，格式由启发式规则猜测——用户手动纠正后，该视频的纠正结果会被永久记住（见下文VrFormatOverrideService）；
• 「观看距离」：按住即可推远/拉近画面（平面视频缩放图像、全景视频调节视场角）；
• 在其它应用中打开：把当前视频交给 MX Player / VLC、Skybox / Pigasus 等 VR 播放器，或桌面端自定义外部播放器；优先使用本地/已下载文件，兜底「复制链接」；
• 桌面端支持把本地视频文件拖拽进窗口立即播放。

在源码侧，VR 格式判定由 lib/app/utils/vr_format_detector.dart 实现为两阶段检测：阶段 A 用「标题 + 简介 + 标签」文本负责怀疑（召回率压到 1.0，绝不漏真 VR），阶段 B 用真实宽高比做判决（≈2:1 才是等距投影，≈16:9 一律否决）。实测 1125 条真实视频中，起播前只有 38% 能拿到file.width/height，因此无尺寸时返回 null 并推迟到开播后复判。文件名信号被证伪（816 条是 UUID），标签必须精确匹配 id 而非子串包含（vrchat/3d_custom_girl含vr/3d子串却与 VR 无关），否定词（VRあり/Flat&）与正向词（VR Version/VR版）必须分开处理——这些注释都直接沉淀在检测器源码中。

手动纠错的持久层是 lib/app/services/vr_format_override_service.dart：把用户定死的VrSourceFormat（投影 + 左右眼编排）永久写入video_vr_override表，下次打开同一视频时读回并压过一切机器推断。设计上刻意不做任何按时间的清理——手动覆盖代表「机器认错了、以我为准」，必须永远有效；因此它不复用跟随浏览历史一起删除的video_playback_history表。本地文件侧的行跟随条目删除（同事务），文件在应用外被挪走/改名时按指纹认领（adoptVrOverrideByFingerprint）。

Meta Quest / VR 空间体验

Quest 支持作为独立的questAPK 交付，基于Meta Spatial SDK构建；普通 Android 构建完全不含该 SDK 代码，minSdk保持不变。这是文档中技术含量最高、也最具差异性的部分：

• 应用常驻空间环境：从 Quest 主界面启动即进入常驻沉浸空间，浏览、搜索、评论、软键盘等全部功能以 2D 面板悬浮在眼前，功能无裁剪。面板微弧（30° 弧，默认宽度 1.6 m 时约相当于「3000R」曲率显示器）；固定的是弧而非半径，因此窗口无论拉宽拉窄，曲率观感一致。
• 三窗口、一套手势：应用面板、屏幕与控制面板各有独立边框——扳机键抓取拖动窗口本体，拖边缘、拽角绕中心缩放，窗口始终面向用户，尺寸与位置会被记忆。头部追踪稳定前不会闪现窗口。
• 播放器化身空间屏幕：打开视频可（可选）自动切换。屏幕形状支持平面或三种弯曲度；距离、宽度与宽高比按宽高比分别记忆，回到 4:3 视频时恢复你为 4:3 设置的布局。视频格式覆盖 2D / 3D、半幅/全幅 SBS、半幅/全幅 over-under、180°/360° 等距投影，自动检测且可手动纠正；EAC 与 fisheye 被识别后标记为不支持并转交外部播放器。播放支持 0.5×–3.0× 倍速、循环、音量、带目标时间与差值的拖拽预览、屏幕内缓冲指示，面板上还有时钟与电量。
• 空间内「继续观看」：与 2D 应用同源的分类视频池（来源列表、订阅、播放列表、收藏、下载、稍后观看）带封面展示，无需离开空间即可切换；下一个视频加载失败时面板显示加载状态并退回原视频。
• 过期链接处理：播放源在到期前刷新，播放中遇到 404 会触发刷新并从原位置续播。
• 场景：支持透视（passthrough）或虚空两种。
• 空间画廊：一组数十张图片（及混入其中的视频）作为「一个大舞台 + 一条缩略图胶片」，是单一对象而非几十个图层；支持 3 / 5 / 10 / 20 秒幻灯片、标准/原图质量、在舞台侧向拖动翻页；竖版图片被适配进 16:9 框内，避免 9:16 插图悬在头顶。
• 手或控制器：手部使用官方射线 + 捏合，在面板外任意位置捏合可切换控制面板；控制器上 A/X 播放暂停、B/Y 关闭面板或返回应用、Menu 打开设置，扳机键无需瞄准即可抓取屏幕，摇杆左右滚动带加速（轻推 5 秒，长按加速至每秒 15 分钟）并上下推远/拉近屏幕；摘下头显暂停、戴上恢复，系统重居中会把一切重新摆到眼前。
• 首次启动即教程：空间版并非触屏教程的移植（空间里没有可触摸的画面），而是「空间视频」「空间画廊」两门课程——控制器插图与按钮、摇杆逐帧动画，屏幕、面板、射线按真实几何摆放，每个动作同时演示控制器与裸手两种方式；系统开启「减少动态效果」时显示单张静态说明帧，可随时从设置重看。

原生侧的落点集中在 android/app/src/quest/kotlin 的xr/XrBridge.kt与vr/ImmersiveActivity.kt。从 lib/app/services/xr_immersive_service.dart 可以看到桥接设计：XrBridge在standard与quest两个源集各有一份同名实现，standard 那份是空壳、不注册 MethodChannel，因此普通安卓/桌面上调用会抛MissingPluginException并被吃回「不可用」——调用点只需问isAvailable，无需关心自己跑在什么设备上。沉浸态播放使用 ExoPlayer 而非 libmpv（mpv 渲染不到 Spatial 可绑定的 Surface，代价是 VR 态拿不到 Anime4K / 色觉滤镜 / 字幕），相关依赖全部以questImplementation挂载，见 android/app/build.gradle。

浏览与发现、画廊、社区、账号与本地数据

• 浏览与发现：多类别搜索（视频 · 画廊 · 帖子 · 用户 · 论坛）、iwara.tv⇄iwara.ai运行时站点切换、news.iwara.tv新闻流集成、Oreno3d 标签源集成、订阅与灵活筛选、桌面/平板自适应布局。
• 画廊：图片平滑缩放与平移，画廊查看器带质量设置。
• 社区：论坛（创建/编辑主题与回复）、帖子（浏览与评论）、评论（浏览与回复）、私信（浏览与回复）、应用内通知。
• 账号与分享：用户认证、资料管理、关注系统；分享视频/画廊/帖子/主题/用户；Android 深链回传——在其它应用打开 Iwara 链接会跳回 2i。
• 本地数据与工具：本地历史（视频 · 画廊 · 帖子 · 论坛）、带自定义收藏文件夹的本地收藏、下载（beta）（视频/画廊/单文件，可自定义路径，Android 支持外部 SD/TF 卡）、配置与历史的备份恢复、描述/帖子/评论/论坛/私信等的翻译、PIN/生物识别应用锁、「记住上次音量」（PC）。

技术栈一览

快速开始与构建

克隆与首次运行

# 1. 克隆 git clone https://gitcode.com/gh_mirrors/lo/LoveIwara.git cd LoveIwara # 2. 校验工具链 flutter doctor # 3. 安装依赖 flutter pub get # 4. 运行（自动选择已连接设备） flutter run --flavor standard # Android 必须带 flavor —— 见下方说明 # …或指定平台（桌面 / iOS 不需要 flavor）： flutter run -d windows # macos / linux / ios

关键约束：Android 双 product flavor

文档强调：Android 以两种 product flavor 交付。

• standard：普通手机/平板构建（minSdk 24，全 ABI）；
• quest：Meta Quest / Horizon OS 构建（minSdk 34，仅 arm64，打包约 50 MB 的 Meta Spatial SDK）。

一旦定义了 product flavor，AGP 便不再存在「无 flavor」的变体，因此任何 Android 的flutter run/flutter build都必须传--flavor，裸命令会直接失败。

这一约束在 android/app/build.gradle 中有完整的源码级注解：flavor 维度名为platform；standard刻意什么都不覆盖（完整继承defaultConfig，保证「standard 包零增重」）；quest通过minSdk 34抬升、ndk { abiFilters 'arm64-v8a' }限流。源码还记录了一次实战教训：光在 flavor 里写abiFilters不够，全局的splits.abi仍会产出app-armeabi-v7a-quest-*.apk与app-x86_64-quest-*.apk——那两个包各有 5 个本 ABI 的 .so 却一个 Spatial .so 都没有（libMetaSpatialSDK只发 arm64），装上进沉浸式即UnsatisfiedLinkError。最终修法是用新版 Variant API 在androidComponents.onVariants里直接关闭 quest 变体的非 arm64 产物。Meta Spatial SDK 依赖（meta-spatial-sdk/-toolkit/-vr/-isdk/-compose，均为 0.13.2）必须挂在questImplementation而非implementation，否则会撑大 standard 包并砍掉全部 minSdk 24 存量用户；Quest 控制条的 Compose 实现收在独立的 android/questui 模块，:app不应用 Compose 编译器插件。

全量开发环境配置

前置要求：Flutter SDK（建议最新稳定版）、Dart SDK、Git；推荐 IDE 为 Android Studio / VS Code / Cursor + Flutter 插件。

各平台具体要求：

• Windows：Windows 10+（64 位）、Visual Studio 2022+、Windows 10 SDK；用flutter doctor -v校验。
• macOS：较新 macOS + Xcode + CocoaPods；sudo gem install cocoapods。
• Linux：Ubuntu/Debian 执行sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev；Fedora 执行sudo dnf install clang cmake ninja-build gtk3-devel。
• Android：Android Studio + Android SDK + 模拟器/真机；iOS：Xcode + 模拟器/真机 + Apple Developer 账号（发布用）。

构建 Release 产物

flutter build apk --release --flavor standard # Android APK（手机 / 平板） flutter build appbundle --release --flavor standard # Android AAB flutter build apk --release --flavor quest --target-platform android-arm64 # Meta Quest APK flutter build ios --release # iOS flutter build windows --release # Windows flutter build macos --release # macOS flutter build linux --release # Linux

常用命令与故障排查

dart run slang # 重新生成 i18n 字符串 flutter analyze # lint flutter test # 运行测试 flutter clean # 清理构建缓存 flutter devices # 列出已连接设备

依赖冲突：flutter pub cache repair && flutter clean && flutter pub get；模拟器：flutter emulators && flutter emulators --launch <emulator_id>。

另外文档特别提示：编辑任意lib/i18n/*.i18n.yaml后，必须用dart run slang重新生成本地化字符串；完整依赖清单见 pubspec.yaml，个别包需要额外配置步骤（如 Objective-C 9.6.1 上游构建钩子损坏，仓库在dependency_overrides中锁定回 9.6.0）。

Android 签名配置

文档给出了完整的签名流水线（四步）：

1. 生成 keystore（在android/app目录内执行）：

keytool -genkeypair -v -keystore keystore.jks -alias <your_key_alias> -keyalg RSA -keysize 2048 -validity 10000

确保keystore.jks位于android/app。

2. 在android/app/build.gradle中配置签名：

signingConfigs { release { storeFile file("keystore.jks") storePassword System.getenv("KEYSTORE_PASSWORD") ?: project.findProperty("MY_KEYSTORE_PASSWORD") keyAlias System.getenv("KEY_ALIAS") ?: project.findProperty("MY_KEY_ALIAS") keyPassword System.getenv("KEY_PASSWORD") ?: project.findProperty("MY_KEY_PASSWORD") } }

并在android/gradle.properties中加入占位：

MY_KEYSTORE_PASSWORD=${KEYSTORE_PASSWORD} MY_KEY_ALIAS=${KEY_ALIAS} MY_KEY_PASSWORD=${KEY_PASSWORD}

仓库源码确认这套逻辑与构建配置一致（android/app/build.gradle 中release构建类型启用signingConfigs.release，且minifyEnabled false/shrinkResources false）。另有工程细节：debug与profile构建类型都追加了 applicationId 后缀（.debug/.profile），使调试包可与正式版并排安装、互不干扰数据——profile 此前没有后缀、applicationId 与正式版完全相同，装到自用机会撞签名导致INSTALL_FAILED_UPDATE_INCOMPATIBLE，已修正。

3. GitHub Actions 注入密钥：在仓库 Secrets 中配置KEYSTORE_BASE64（keystore.jks的 base64）、KEYSTORE_PASSWORD、KEY_ALIAS、KEY_PASSWORD，然后在 CI 工作流中：

env: KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }} KEY_ALIAS: ${{ secrets.KEY_ALIAS }} KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }} steps: - name: Setup Keystore run: | echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode > android/app/keystore.jks shell: bash

4. 构建：flutter build apk --release --flavor standard输出在build/app/outputs/flutter-apk/app-standard-release.apk；Quest 构建flutter build apk --release --flavor quest --target-platform android-arm64输出app-arm64-v8a-quest-release.apk。

国际化与标签本地化工程

这是本文档除 Quest 之外的第二大技术主题，也是仓库中工具链最完整的部分。

12 门界面语言

UI 共支持12 种语言：English · 简体中文 · 繁體中文 · 日本語 · 한국어 · ภาษาไทย · Bahasa Indonesia · Tiếng Việt · Español · Русский · Français · Deutsch——Quest 空间面板也跟随应用内语言设置而非系统语言。除原始四门（en / zh-CN / zh-TW / ja）经过人工校对外，其余 8 门为机器首轮翻译。资源文件位于 lib/i18n，基准语言为en（lib/i18n/en.i18n.yaml），每门语言的现状与维护命令详见 docs/i18n/README.md：

dart run tool/i18n_check.dart # 查看每门语言的缺失/多余/占位符不符/疑似未翻 dart run tool/i18n_sync.dart <locale> # 给某门语言补齐 en 新增的 key（占位保留原文）

Iwara 标签本地化架构

Iwara 原始标签是英文风格 key（如mother、blue_archive）。应用内置一份社区维护的词典，把每个标签映射到简中 / 繁中 / 日语 / 英语四种译名，使标签在详情页、搜索与标签列表页按当前界面语言渲染。全套工具位于 tool/data/iwara_tags：

• fetch_iwara_tags.dart：从 Iwara API 抓取全部标签存为本地快照的命令行工具；
• iwara_tags.json：抓取的原始元数据（2669 个标签）；
• iwara_tags_localized.json：AI 产出的四语言映射（按 A-Z 排版）；
• iwara_tags.min.json：App / CDN 实际消费的合并产物（合并原始元数据type/sensitive与四语言译名）；
• overrides.json：人工修正层，永远压过 AI 译名，重译不碰它；
• build_localized_min.dart：合并脚本（原始元数据 → AI 译名 → overrides），生成 min 文件并同步一份到打包资源。

合并产物结构（键名缩写以省体积）：

{ "version": 1, "count": 2669, "tags": { "mother": { "y": "general", // type "s": 0, // sensitive，0/1 "n": { "zh-CN": "母亲", "zh-TW": "母親", "ja": "母親", "en": "Mother" } } } }

交付双渠道：打包兜底（assets/data/iwara_tags.min.json，离线即用）+ jsDelivr CDN 热更新（无需发版即可更新译名）。运行时代理由 lib/app/services/tag_localization_service.dart 的TagLocalizationService统一处理。

运行时实现：内存策略、展示与搜索

从源码看TagLocalizationService的设计非常克制：

• 内存精简：内存里只物化「当前语言译名 + 原始 key + 评级位」这一份_SlimTag映射（译名缺失回退英文，仍只存一份字符串），不保留全部四种语言；切换语言时从数据源（CDN 缓存 → 打包资源，取更新的那份）重建，降低内存占用。
• 展示：localize(tagId)把tag.id转为当前语言译名，未收录或译名缺失回退到美化后的原始 key（3d_custom_girl→3d custom girl）；localizeWithId在译名与 key 不同时附带原始 key（如母亲 (mother)）。
• 搜索：searchLocal支持「当前语言译名 / 原始 key」双向匹配（输入「母亲」或mother都能命中），按「key 完全相等 > key 前缀 > 译名前缀 > 译名包含 > key 包含」排序；mergeLocalFirst把本地命中结果合并到接口结果之前并按 id 去重。
• 语言回退：currentLocaleKey()把界面语言映射到词库语言——zh-CN/zh-TW/ja/en直用，其它zh地区回退简中，其余 8 门界面语言一律回退英文。
• 版本与热更新：lib/app/services/tag_dictionary_refresh.dart 定义了DictionarySnapshot（version/rev内容指纹 /count/builtAt）。历史实现用「条目数变了才算更新」，纯译名修正判不出来；现在构建脚本给产物写入内容指纹rev，任何一个字变了它都变，配合builtAt判定先后——isStaleIncoming专门拦截 jsDelivr@master缓存滞后（十几小时到几天）造成的「远端比本地旧还顶掉本地」；冷启动时「缓存 vs 打包资源」用assetBeatsCache判定谁该赢。
• 搜索补路：lib/app/services/tag_name_index.dart 的TagNameIndex维护全语言名称索引，只做精确匹配（折叠大小写、全角 ASCII、片假名=平假名、丢标点空白），用于把用户输入解析为「精确是哪个标签的名字」并补「日文名 / 英文名」几路文本搜索——因为实测 Iwara 自由文本只搜标题/简介不搜标签，近 30 天搜「原神」文本只召回 17 条，{tags:[genshin_impact]}有 324 条。

Oreno3d 元数据本地化

第三方 Oreno3d 元数据（原作 / 角色 / 标签）以同样方式本地化：词典在 tool/data/oreno3d_tags，打包资源 + jsDelivr CDN，在视频详情页与搜索卡片上按当前语言展示。工具链细节：

• fetch_oreno3d_tags.dart 逆向 oreno3d 列表页 HTML 产出快照（809 原作 / 1579 角色 / 166 标签），支持--proxy <host:port>（Cloudflare 校验）、--cookie（复用cf_clearance）、--changes <path>（增量变更清单）、--no-diff等选项；
• 合并产物主键采用type/id而非日文原名——2554 个词条中只有 2515 个不同日文名，存在38 组跨作品同名词条（如《斯普拉遁》与《崩坏：星穹铁道》的ホタル），旧结构在架构上就无法分别翻译；迁移已无损完成（2554 → 2554，零缺失零孤儿）；
• 运行时Oreno3dLocalizationService（lib/app/services/oreno3d_localization_service.dart）与 Iwara 侧同构：内存只物化当前语言译名，详情页对象按(类别, id)精确映射，卡片纯字符串标签按「日文原名 → 译名」兜底，缺失回退日文原名；由于全量词库随包内置，搜索里选择 Oreno3d 实体完全离线，按「译名 / 日文原名 / id」检索并按作品数排序。

回退规则与维护边界（重要设计决策）

两份标签词库仅维护 zh-CN / zh-TW / ja / en 四门，刻意不扩展到其余 8 门界面语言。官方文档与 docs/i18n/README.md 给出的理由是：

• AI 翻译成本：两份词库合计 2600+ 条 ACG / Vtuber / 同人黑话且持续新增，每多一门语言就要对存量词条重跑一轮翻译，之后每次增量再翻一遍，维护成本随语言数线性增长；
• 错译更难发现：这类词条依赖亚文化圈约定俗成的译法（角色梗、作品别称、同人称呼），不是字面直译；维护者无法校对该语言时，宁可标签缺译退回英文，也不提供无法校对的翻译。

因此实际表现为：界面语言不在四门之列时，标签不翻译成该界面语言，而是回退显示词库里的英文译名（如mother→Mother）；只有标签完全不在 2600+ 词库内时，才退到美化后的原始 key（如some_new_tag→some new tag），且这与界面语言无关——四门语言遇到未收录标签同样显示原始 key。

贡献修正流程

文档给出维护者/贡献者的标准流程：

1. 编辑人工可读的 iwara_tags_localized.json（逐标签zh-CN/zh-TW/ja/en）——注意人工修正请写进overrides.json而不是直接改 AI 产出，否则随时可能被整批重译覆盖；
2. 重新生成合并产物与打包资源：dart run tool/data/iwara_tags/build_localized_min.dart；
3. 同时提交源文件与生成的iwara_tags.min.json。

另外，仓库还沉淀了一套面向 LLM 的 ACG 标签翻译提示词（见 tool/data/iwara_tags/README.md 全文）：包括「严防拍脑袋音译」（amatsuka_uto应译「天使Uto」而非「天鬼宇都」、mornye应取《鸣潮》官方译名「莫宁」）、「严防机翻与语境错位」（parody在同人库中指「原作」而非「恶搞」、x_ray指 NSFW 专用术语「断面图」）、「严防偷懒与格式破损」（必须无一遗漏输出纯净 JSON）三条铁律，可直接复制给大模型用于后续翻译或校对。翻译管线本身是「分块切割（按字母序 7 块，每块约 380 条）→ 并发 7 个 ACG/Vtuber/3D 动作/NSFW 专项 AI 子代理 → 世界知识库映射 → Python 去重校验并 A-Z 归并」，且经历过全量二次纠错审查（如繁中「守望先锋→鬥陣特攻」「小馬寶莉→彩虹小馬」等社区惯例对齐）。

路线图与已知限制

Quest 支持已经落地，以独立 APK 由独立 CI 任务构建，普通 Android 构建不受影响。头显侧仍开放的问题（官方文档原文）：空间面板的 GPU 内存释放路径尚不有效；空间场景与 Flutter 共享主线程、帧成本从未测量；应用面板基于 Activity，官方建议迁移到更轻的 View 面板；EAC 与 fisheye 投影可识别但转交外部播放器而非渲染。此外：下载仍标记为 beta；Linux 能构建但缺少测试机器未实测。

结语

Love Iwara 在单套 Flutter 代码库上同时解决了两类高难度问题：一是把完整 Iwara 客户端（含媒体播放、社区、下载、翻译）搬进 Meta Quest 空间环境并做手势/场景适配，二是通过「AI 并发翻译 + 人工修正层 + 双渠道交付 + 内容指纹热更新」构建 2600+ 标签的多语言词库工程。无论是想研究 Flutter 多平台架构、Quest 空间化集成，还是大型 i18n 数据管线，仓库的源码注释、android/app/build.gradle、lib/app/services/tag_localization_service.dart 与 tool/data/iwara_tags/README.md 都是可直接深入的一手材料。

• 移动开发
• 桌面应用
• 音视频
• 视频