Han1mePlus多平台构建指南：Android、iOS、macOS、Windows、Linux打包全流程

Han1mePlus 是一款基于 Flutter & Dart 构建的 Hanime1 跨平台第三方客户端，支持 Android、iOS、macOS、Windows 与 Linux 五大平台。本文是一份 Han1mePlus 多平台构建与打包的完整指南：从环境准备，到各平台的编译、签名与安装包生成，带你一步步完成 Han1mePlus 全平台打包流程，即使是 Flutter 新手也能照着做。

构建前环境准备（所有平台通用）

在开始任何平台的构建之前，先准备好以下三样东西：

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/ha/Han1mePlus.git cd Han1mePlus

2. 检查工具链是否就绪：

flutter doctor flutter pub get

3. 应用版本号集中在 pubspec.yaml（当前为1.2.4+25），打包前如需发布新版本，先在这里修改version。

💡 提示：项目启用了generate: true与flutter_localizations，flutter pub get会自动生成多语言（简中、英文、繁中，见 lib/l10n/）代码，无需手动处理。

Android 打包：APK 与 AAB 一键构建

Han1mePlus 的 Android 端最低支持 Android 8.1（API 27），目标与编译 SDK 均为 37，相关配置位于 android/app/build.gradle.kts。构建环境使用 Gradle 9.0.0（gradle-wrapper.properties）与 AGP 8.13.0。

构建步骤：

# Debug 版（可直接安装） flutter build apk --debug # Release 版（推荐分发用 AAB，体积更小、可上架） flutter build appbundle --release

产物位置：

• APK：build/app/outputs/flutter-apk/app-release.apk
• AAB：build/app/outputs/bundle/release/app-release.aab

两个值得注意的细节：

• Release 签名：当前配置中 release 构建直接复用 debug 签名（android/app/build.gradle.kts 的signingConfig = signingConfigs.getByName("debug")），并启用了 R8 压缩（isMinifyEnabled）。若要上架应用商店，请替换为自己的正式签名。
• 体积优化：debug 包会自动剔除armeabi-v7a、x86、x86_64架构的 so 库（android/app/build.gradle.kts 中的androidComponents配置），只保留arm64-v8a，加快调试编译速度。
• 原生代码：Android 端还包含 Kotlin 原生类（如 EchHttpClient.kt 的 ECH 网络客户端），Gradle 会自动一并编译，无需额外操作。

iOS 打包：从 pod install 到 IPA 导出

iOS 构建只能在 macOS 上进行，需要 Xcode 与 CocoaPods。iOS 端包含多个 Swift 原生组件（网络、DNS、代理等，位于 ios/Runner/），如 Han1meHttpClient.swift。

构建步骤：

cd ios pod install cd .. # 生成 ipa（需先配置签名） flutter build ipa --release

关键点说明：

• ios/Podfile 使用use_frameworks!动态库模式集成 CocoaPods，pod install必须在flutter pub get之后执行（它依赖Generated.xcconfig）。
• ios/Runner/Info.plist 已开启NSAllowsArbitraryLoads（允许非 HTTPS 请求），并声明了 Face ID 解锁的用途描述——这与应用内的应用锁功能（lib/src/features/auth/）配套，无需额外修改。
• 签名配置：在 Xcode 中打开ios/Runner.xcworkspace，选择 Runner 目标 → Signing & Capabilities，填入你的 Team 与 Bundle ID。个人测试可用免费账号生成开发证书；发布到 TestFlight / App Store 需要付费开发者账号。
• 构建完成后，.xcarchive位于build/ios/archive/，用 Xcode Organizer 即可导出 IPA。

macOS 打包：一条命令生成 .app

macOS 端与 iOS 共享大部分 Swift 代码，构建更简单——不需要手动 pod install，Flutter 工具链会托管整个过程（Pod 配置见 macos/Podfile）。

构建步骤：

flutter build macos --release

产物为build/macos/Build/Products/Release/Han1me+.app，可直接双击运行或拖入「应用程序」文件夹。

注意事项：

• 最低系统要求：macos/Podfile 声明platform :osx, '12.0'，即 macOS 12 Monterey 及以上。
• 应用标识：显示名为Han1me+、Bundle ID 为com.liar.han1mePlus，定义在 macos/Runner/Configs/AppInfo.xcconfig。
• 公证（Notarization）：分发给他人时建议进行签名 + 公证，否则用户首次打开会被 Gatekeeper 拦截；仅供自己使用的本地构建可以忽略。

Windows 打包：MSBuild 编译 + Inno Setup 安装包

Windows 端采用 CMake + Visual Studio 2022 构建，编译配置见 windows/CMakeLists.txt，入口代码在 windows/runner/main.cpp。

构建步骤：

# 前提：安装 Visual Studio 2022（勾选“使用 C++ 的桌面开发”） flutter build windows --release

产物目录为build\windows\x64\runner\Release\，包含han1me_plus.exe及全部运行库。

制作安装程序：

仓库自带 Inno Setup 脚本 windows/installer.iss，会打包 Release 目录内容，生成Han1mePlus-Setup.exe安装包，并支持创建桌面快捷方式（windows/installer.iss）。只需安装 Inno Setup 后用其打开脚本编译即可。

注意：若只打包绿色版（免安装目录），需要把Release目录整体复制分发，其中的data\flutter_assets与动态库不可省略。

Linux 打包：GTK3 依赖与可移植目录

Linux 端依赖 CMake 与 GTK+ 3.0，linux/CMakeLists.txt 通过 pkg-config 检查 GTK：

# Debian / Ubuntu sudo apt install clang cmake ninja-build pkg-config \ libgtk-3-dev libnotify-dev libwebkit2gtk-4.0-dev # 构建 flutter build linux --release

产物说明：

• 最终产物是build/linux/x64/release/bundle/目录（可整体压缩分发），包含han1me_plus可执行文件、lib、data与share子目录。
• 构建时会自动安装桌面集成资源：my_application.desktop 启动项与 com.liar.han1meplus.png 图标（见 linux/CMakeLists.txt），用户安装后应用列表即可正常显示 Han1me+ 图标。
• 若需制作 .deb 或 .AppImage 安装包，可自行基于bundle/目录用dpkg-deb或appimagetool封装，仓库未内置该脚本。

常见构建问题速查

总结：五平台构建命令一览

掌握以上内容，你就完成了 Han1mePlus 全平台构建：日常自测推荐先打 Android APK 或桌面端 Release 版验证功能，再按目标平台补齐签名与安装包。项目入口逻辑可参考 lib/main.dart，应用启动时会初始化播放器引擎、设置存储与 shader 资源复制，理解它有助于排查各平台的启动异常。

⚠️ 本项目遵循 AGPL v3.0 协议（见 LICENSE），二次分发时请遵守协议条款；本应用为非官方客户端，请自行确保使用合规。