安装 Hanafubuki
在下载页选择安装包或便携版，并完成首次启动。
Hanafubuki 提供两种获取方式：安装包把应用装进系统，便携版是一个解压即用的 Launcher。两者都在下载页提供，并且都会自动识别当前系统。
先选择一种
| 安装包 | 便携版 | |
|---|---|---|
| 使用方式 | 安装后从桌面或开始菜单启动 | 解压后直接运行 Launcher |
| 应用本体 | 包含在安装包中 | 由 Launcher 下载、校验并在损坏时修复 |
| 数据位置 | 系统的应用数据目录 | 程序旁的 .hanafubuki-launcher 目录 |
| 更新 | 推荐格式支持在应用内检查并安装 | 见关于与更新 |
| 适合 | 长期在这台机器上使用 | 移动硬盘，或需要多份互不干扰的环境 |
只从官方来源下载
下载页的链接都指向项目在 ModelScope 与 Hugging Face 的发布仓库，页面会自动选择先响应的来源。请不要从第三方转载地址获取安装包。
在下载页获取
页面分为“安装包”和“便携版”两屏，右侧指示器显示当前位置，顶部的版本切换按钮可以在两者之间跳转。
Windows 只提供 x86_64；macOS 与 Linux 同时提供 x86_64 和 ARM64。Apple 芯片机型请选择“macOS（Apple 芯片）”。
安装包格式
同一个版本会同时发布多种格式。不确定时选择标注为推荐的一项。
| 平台 | 格式 | 说明 |
|---|---|---|
| Windows | 安装程序（.exe） | 推荐。常规安装流程，支持应用内更新 |
| Windows | MSI 安装包 | 适合批量部署；不参与应用内更新 |
| Windows | 免安装压缩包 | 解压即用；不参与应用内更新 |
| macOS | 磁盘映像（.dmg） | 推荐。打开后拖入“应用程序”，支持应用内更新 |
| macOS | 应用归档（.app.tar.gz） | 同一个 .app 的压缩形式 |
| Linux | AppImage | 推荐。单文件运行，支持应用内更新 |
| Linux | Debian 包（.deb） | 通过系统包管理器安装；不参与应用内更新 |
| Linux | RPM 包（.rpm） | 通过系统包管理器安装；不参与应用内更新 |
不参与应用内更新的格式仍然可以检查更新，应用会改为提供当前平台的手动安装包。
按平台安装
下载安装程序并按提示完成安装，随后从桌面或开始菜单启动。
选择免安装压缩包时，解压到有写入权限的目录再运行其中的可执行文件。
当前 Windows 安装包尚未签名。启动安装程序或免安装版时如果出现 Windows 已保护你的电脑。Microsoft Defender SmartScreen 阻止了无法识别的应用启动。运行此应用可能会导致你的电脑存在风险。，请先确认文件来自本站，再点击提示中的“更多信息”，然后点击“仍然运行”。
免安装压缩包不等于便携数据
Windows 的免安装压缩包只是省去安装步骤，数据仍然写入系统的应用数据目录。需要数据跟着程序走时，请使用下面的便携版 Launcher。
便携版
便携版是一个独立的 Launcher。设置、日志、应用本体和实例数据都保存在它旁边的 .hanafubuki-launcher 目录里，不写入系统安装信息。
下载对应平台的 Launcher 压缩包，解压到有写入权限的目录；不要放在只读介质或系统目录中。
.hanafubuki-launcher 目录一起复制到新位置。Windows 阻止 Hanafubuki Launcher 启动
当前 Windows 便携版同样尚未签名。首次运行 Launcher 时如果 Microsoft Defender SmartScreen 显示
Windows 已保护你的电脑，请先确认压缩包来自本站，然后点击“更多信息”，再点击出现的“仍然运行”按钮。
“仍然运行”只会在展开“更多信息”后显示。
macOS 提示 Hanafubuki Launcher 已损坏
当前 macOS 便携版同样尚未签名。确认压缩包来自本站后，在“终端”输入
xattr -dr com.apple.quarantine 并加一个空格，将解压得到的 Hanafubuki Launcher.app
从“访达”拖入终端窗口，再按回车。完整命令类似：
xattr -dr com.apple.quarantine "/实际路径/Hanafubuki Launcher.app"完成后重新打开 Launcher。命令必须指向实际的 .app；不要直接照抄示例中的“实际路径”。
Launcher 还会处理这些情况：
- 首次运行时扫描自己所在的目录，把放在旁边的 WebUI 目录接管为实例。
- 本体文件缺失或损坏时按清单重新下载并修复。
- 更新源都不可用时跳过远程检查，直接用已下载的版本启动。
- 读取系统代理配置，用于自身的下载请求。
Windows 首次运行的两项准备
Launcher 在 Windows 上需要长路径支持和 Visual C++ 运行库。缺少时会各请求一次管理员权限来写入注册表或安装运行库，之后仍以普通用户身份运行。取消授权会停在重试界面。
首次启动
应用会准备 Python、Micromamba 和 Git 等运行组件。保持网络连接并等待准备完成。
若准备失败，前往“设置 → 运行环境”重试或调整下载来源，也可以参考运行环境故障排查。
准备完成后，继续阅读快速开始安装或导入第一个 WebUI。