FMCL - Fusion Minecraft Launcher

一个基于 CustomTkinter 的现代 Minecraft 启动器，集 版本管理、多模组加载器（Forge/Fabric/NeoForge/Quilt 等8种）、国内 BMCLAPI 镜像加速、模组与整合包管理、服务器一键开服、P2P 陶瓦联机、存档备份、AI Agent 助手、音乐播放器、性能监控悬浮窗、动态主题、成就系统、崩溃分析、安全加密、插件系统、多语言、自动更新 于一身——用开源的力量，打造真正全能的游戏伴侣。

功能特点

完整功能列表详见 docs/FEATURES.md

界面预览

┌──────────────────────────────────────────────────────────────────────────────────┐
│  ⛏ FMCL   Minecraft Launcher   ⬆ 更新  🔄 刷新  ⚙ 设置  │
│  [🎮 游戏] [💾 备份] [🖥 开服] [🔗 链接] [🌐 联机] [🎵 音乐] [🤖 AGENT] [🏆 成就] [📜]│
├────────────┬──────────────────────────────┬──────────────────────────────────────┤
│ 👤 账号  │  📦 已安装版本  ⚙  3 个版本 │  📥 安装新版本               │
│ ⭐ Steve │  ─────────────────────────── │  ──────────────────────      │
│            │  │ 1.20.4          🧩⚙[X] │  │  版本 ID:  [1.20.4      ]   │
│ 🎨 皮肤   │  │ 1.20.4-forge-49🧩⚙[X] │  │  模组加载器: [无      ▼]     │
│ ✅ skin.png│  │ fabric-loader-0🧩⚙[X] │  │  提示: 安装 Forge 会同时... │
│ [选择][🗑] │  │                        │  │  [📥 安装版本]              │
│            │  │                        │  │                              │
│ 📋 日志   │  │                        │  │  📋 快速选择                 │
│ [14:30:01] │  │                        │  │  ──────────────────          │
│ 环境初始化 │  │                        │  │  📦 正式版  🔬 测试版        │
│ 完成       │  │                        │  │  [📦 1.21.4] [📦 1.21.3]    │
│            │  └────────────────────────┘  │  [📦 1.21.2] [📦 1.21.1]    │
│            │  [🚀 启动游戏] [⏹]           │  ◀  1/12  ▶                 │
│            │                              │                              │
│ [清空日志] │                              │                              │
├────────────┴──────────────────────────────┴──────────────────────────────┤
│  ✅ 已安装 3 个 | 正式版 842 个 | 测试版 312 个    ████░░ 45% │
└──────────────────────────────────────────────────────────────────────────────────┘

环境要求

安装

方式一：从 Release 下载（推荐）

前往 Releases 页面下载适合你平台的安装包：

注意：自 v2.10.3 起，不再通过 GitHub Actions 构建并发布 macOS（.dmg）与 Linux（.deb / .AppImage）二进制包。Linux 用户请使用下方「方式二：Linux 一键安装」脚本进行安装；macOS 用户请参考「方式三：从源码运行」。

安装说明

• Windows: 双击 .exe 安装包，按向导完成安装。安装包已内置 7-Zip（24.09 版本），无需联网即可自动安装
• Linux: 请使用下方「方式二：Linux 一键安装」脚本
• macOS: 请参考下方「方式三：从源码运行」

方式二：Linux 一键安装

curl -fsSL https://raw.githubusercontent.com/Janson20/FMCL/main/scripts/install.sh | bash

脚本自动完成：安装系统依赖 → 安装 uv → 克隆项目 → uv sync → 注册 fmcl 命令。

支持 Debian / Ubuntu / Fedora / RHEL / CentOS / Arch / openSUSE，安装完成后直接运行 fmcl 即可启动。
自定义安装目录：./scripts/install.sh ~/.local/share/fmcl

方式三：从源码运行

# 克隆仓库
git clone https://github.com/Janson20/FMCL.git
cd FMCL

# 安装 Python 依赖（Windows）
pip install -r requirements-windows.txt

# 安装 Python 依赖（macOS / Linux）
pip install -r requirements-unix.txt

# 运行启动器（GUI 模式）
python main.py

# 运行 Agent CLI 模式
python main.py --agent "帮我安装最新版"
python main.py -A              # 交互模式

💡 建议使用虚拟环境：python -m venv .venv && source .venv/bin/activate
Linux 用户请参阅 docs/LINUX_FILE_LOCATIONS.md 了解 FHS 标准下的文件存储路径

快速开始

安装版本

1. 在右侧面板输入版本号（如 1.20.4）
2. 选择模组加载器（可选）：Forge / Fabric / NeoForge / Quilt / LiteLoader / LegacyFabric / Cleanroom / OptiFine
3. 点击「📥 安装版本」，等待完成

启动游戏

1. 在左侧「已安装版本」列表中点击要启动的版本
2. 点击底部「🚀 启动游戏」

常用操作

• 安装模组：已安装加载器的版本右侧点击 🧩 按钮，搜索安装 Modrinth 模组
• 安装整合包：点击「📦 安装整合包」，选择 .mrpack 文件或从 Modrinth 下载
• 开服：切换到"🖥 开服"标签页，安装并启动 Minecraft 服务器
• 备份存档：切换到"💾 备份"标签页，手动或自动备份存档

完整使用说明详见 docs/USAGE.md
配置项说明详见 docs/CONFIGURATION.md

项目结构

FMCL/
├── main.py                # 程序入口
├── launcher/              # 启动器核心逻辑
├── ui/                    # CustomTkinter 界面
│   ├── app.py             # 主窗口（Mixin 组合模式）
│   ├── agent/             # AI 智能助手子系统
│   └── windows/           # 独立子窗口
├── downloader.py          # 多线程/异步下载器
├── modrinth.py            # Modrinth API 集成
├── curseforge.py          # CurseForge API 集成
├── mirror.py              # BMCLAPI 镜像源
├── backup_manager.py      # 存档备份管理
├── secure_storage.py      # 安全存储（Fernet 加密）
├── config.py              # 跨平台配置管理
├── validation.py          # 输入验证
├── updater.py             # 自动更新
├── scripts/               # 构建/发布脚本
├── tests/                 # 测试
└── docs/                  # 文档
    ├── FEATURES.md        # 完整功能列表
    ├── USAGE.md           # 详细使用指南
    ├── ARCHITECTURE.md    # 项目架构与技术栈
    ├── CONFIGURATION.md   # 配置说明
    └── ...

完整项目结构与模块依赖关系详见 docs/ARCHITECTURE.md

开发指南

环境设置

# 安装 Python 依赖
pip install -r requirements.txt

# 安装开发依赖（Linux CI）
pip install -r requirements-dev.txt

# 安装 Git hooks (Husky + Commitlint)
npm install
npm run prepare

常用命令

make dev              # 开发模式运行
make run              # 运行程序
make check            # 检查环境和依赖
make lint             # 代码检查 (flake8 + mypy)
make fix              # 运行常见问题修复工具
make clean            # 清理构建文件

构建

make build            # PyInstaller 构建可执行文件
make build-installer  # Windows NSIS 安装包 (需要 NSIS)
make build-dmg        # macOS DMG 磁盘映像 (仅 macOS)
make build-deb        # Linux DEB 包
make build-appimage   # Linux AppImage

构建问题排查请参考 docs/BUILD_FIXES.md

发布流程

1. 更新 pyproject.toml 和 package.json 中的版本号
2. 提交变更：git commit -m "chore: release vX.X.X"
3. 创建标签：git tag vX.X.X
4. 推送：git push origin main --tags

GitHub Actions 会自动构建 Windows 安装包并创建 Release（自 v2.10.3 起不再自动构建 macOS / Linux 二进制包，如需可使用上方 make build-dmg / make build-deb / make build-appimage 在对应平台本地构建）。

详见：CONTRIBUTING.md | docs/SETUP.md

提交规范

本项目使用 约定式提交：

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
refactor: 重构代码
perf: 性能优化
chore: 构建/工具变动

故障排除

查看完整指南：docs/TROUBLESHOOTING.md

许可证

• v2.8.4 及以前版本：使用 MIT License
• v2.8.4 以后版本：使用 GNU General Public License v3.0

Copyright (c) 2026 FMCL Team