在 iOS 设备上运行 Minecraft Java 版，过去一直是一个听起来很美好、落地却很折腾的目标。尤其当你想玩 26.x 版本，还要装模组、光影，甚至整套整合包，很多人第一反应是必须准备一台 Windows 电脑，或者越狱后去改系统文件。而 Amethyst (Air) 这类工具的出现，把整个流程从“电脑 + 越狱”压缩成“一台 iPhone/iPad 直接安装”，配合 Fabric 与 Iris，可以在移动设备上体验与 PC 相近的 Java 版模组生态。下面按顺序拆开讲，从运行原理讲到安装配置，再到日志排查，尽量让没有接触过 Java 版启动器的人也能按步骤走通。
1. 先弄清楚：iOS 上的 Java 版 MC 为什么绕不开一层运行环境
很多玩家第一次接触 Amethyst 时会有一个疑问：Minecraft 手机上不是直接下载就能玩吗？为什么换成 Java 版后，又冒出来“运行环境”“加载器”“光影前置”这些概念。这里要先区分版本，才有后面的操作逻辑。
1.1 基岩版和 Java 版不是同一个程序
Minecraft 目前存在两条主要产品线：基岩版和 Java 版。基岩版使用 C++ 编写，针对移动端、主机端优化，iOS 上的原生 Minecraft App 就是基岩版。Java 版则是在 JVM 上运行的 Java 程序，使用 Java 编写，它的启动、资源加载、模组体系都依赖 Java 运行时。
这两套版本的世界存档不完全通用，模组接口也不一样。基岩版的 Addon 是“行为包 + 资源包”，Java 版的模组则是 Fabric、Forge 这类加载器体系下的.jar文件，底层直接操作 Java 类和方法。因此，iOS 设备不能直接打开一个 Java 版整合包，系统里先得有一层“能跑 Java 程序”的容器。
在常规电脑上，这层容器是玩家自己安装的 Java JDK/JRE，再加一个启动器。在 iOS 上，普通 App 不能像桌面系统那样随意运行外部 Java 进程，所以需要像 Amethyst (Air) 这样的客户端，把 Minecraft Java 版游戏本体、JVM 运行时、模组目录和资源包目录整合到一个受控的 App 沙盒里。
1.2 Amethyst (Air) 在整条链路中的位置
把 Amethyst (Air) 理解为“面向 iOS 的 Minecraft Java 版启动器 + 运行容器”会更直观。它负责四件事：
- 管理 Minecraft Java 版 26.x 的游戏版本文件。
- 为游戏提供可用的 Java 运行环境。
- 启动 Fabric、Iris 等加载器，并把模组、光影包挂载到正确目录。
- 提供文件导入入口，让玩家在设备上完成整合包安装。
Air 是这个产品线里更偏“零电脑”的一种安装或运行模式。玩家不需要在电脑上下载整合包再传到手机，而是直接通过 iOS 设备上的文件 App 或浏览器完成导入。这个“Air”并不代表削弱功能，而是把原来需要电脑处理的文件搬运、解压、路径配置步骤，统一放到设备端完成。
1.3 版本号 26.x 不是随便填的
标题中的“26.x”是 Minecraft Java 版的一个版本代号区间。实际选择版本时，要分清三个层级：游戏版本、Fabric Loader 版本、Iris 版本。只要有一个不匹配，就可能出现启动闪退或模组列表空白。
例如目标是“MC Java 版 26.x”，那么游戏版本最好落到一个具体小版本，比如26.1或26.2。Fabric Loader 需要选择支持该小版本的构建，Iris 也要选择支持该小版本的构建。不同小版本的模组 API 可能不兼容，这也意味着“26.x 整合包”不一定能跨区通用。
建议先有一个判断：学习环境可以追求“最新尝鲜”，日常游玩建议锁定“已经验证过的一组版本组合”。下面会提供记录版本组合的清单，这正是避免反复踩坑的关键。
2. 安装前先确认设备、系统和授权方式
安装 Amethyst (Air) 之前，不需要越狱，不需要准备电脑，但需要确认设备本身满足运行条件。否则装到一半才发现存储空间不足或系统版本过低，会浪费大量时间。
2.1 设备条件速查表
下面表格用于说明常见要求，具体数值要以你实际拿到的 Amethyst 版本说明为准。不同客户端对 iOS/iPadOS 版本下限要求可能不同。
| 检查项 | 常见要求 | 说明 |
|---|---|---|
| 设备类型 | iPhone 或 iPad | 通常建议 A12 及以上芯片，老设备可以运行但模组场景可能吃力 |
| 系统版本 | iOS/iPadOS 较新正式版 | 过旧系统可能无法安装客户端或无法信任描述文件 |
| 存储空间 | 至少预留 8 GB 以上 | MC 游戏本体 + JVM + 整合包 + 光影包会占用较多空间 |
| 网络环境 | 稳定的 Wi-Fi | 首次下载游戏本体和依赖时流量较大 |
| Apple ID | 一个可正常使用的 Apple ID | 用于安装、信任描述文件或后续下载必要资源 |
这里的核心判断是：存储空间比性能更容易被忽略。Minecraft Java 版本身占空间并不算夸张，但一个完整整合包可能包含几十甚至上百个模组，再叠加光影包和缓存文件，容量增长会非常快。建议在安装前先清理设备空间，不要等到导入一半才报“存储不足”。
2.2 你需要准备的材料清单
在实际操作前，先把材料准备好，可以避免操作中断。
- 一台满足系统版本要求的 iPhone / iPad。
- 一个可正常登录的 Apple ID。
- Amethyst (Air) 的安装包或安装通道。
- Minecraft Java 版 26.x 的游戏本体文件，或客户端内置的下载源。
- Fabric Loader 的对应版本文件。
- Fabric API 的对应版本文件。
- Iris 以及它依赖的 Sodium 等性能模组。
- 你实际想玩的整合包、模组
.jar文件、光影包.zip文件。
这里要特别说明：游戏本体和模组资源需要由玩家自己确认来源的合法性和授权范围。文章后续示例只说明安装思路，不提供任何资源下载地址。
2.3 “零电脑、零越狱”的正确理解
Amethyst (Air) 的宣传点是“不需要电脑、不需要越狱”，这不等于绕过 iOS 的安装机制。iOS 系统对非 App Store 应用的安装仍然有限制，首次运行可能需要在“设置 > 通用 > 设备管理”中信任对应的开发者描述文件，否则 App 会提示无法打开。
这是正常的技术流程，不是越狱，也不会修改系统底层。玩家只要按照系统提示完成信任即可。如果在信任之后仍然提示“未受信任的开发者”，通常是因为描述文件过期、设备时间错误或者安装包签名失效，需要回到下载来源确认安装包是否有效。
注意：不要为了绕过系统提示去下载来路不明的“修改版”工具，也不要在设备上尝试关闭系统安全机制。这类操作容易把设备带入不可控状态，而且一旦签名失效，游戏数据也会跟着丢失。
2.4 安装前检查清单
在正式安装前，可以快速过一遍这个清单：
- 设备剩余空间大于 8 GB。
- 系统版本满足客户端要求。
- 已连接稳定 Wi-Fi。
- 已确认 Minecraft Java 版目标小版本号。
- 已确认 Fabric Loader 与 Iris 的版本支持该小版本。
- 已备份设备上现有游戏数据。
- 已把待安装的整合包、模组、光影包整理到文件 App 或 iCloud 云盘中。
这份清单也可以贴在后续任何一次版本升级前复用。
3. 安装 Amethyst (Air) 并先跑通原版 26.x
很多人拿到整合包后第一件事就是全部导入，然后直接启动，结果报错一大堆。正确顺序是先装客户端，再导入游戏本体，先用纯原版跑通一次，最后才加载 Fabric、Iris 和模组。
3.1 安装客户端与首次打开
在 iOS 设备上，用 Safari 打开 Amethyst (Air) 的下载页面，点击下载按钮，按系统提示完成安装。首次打开如果出现“未受信任的开发者”提示，去“设置 > 通用 > 设备管理”找到对应描述文件并信任，然后重新打开客户端。
首次启动后，客户端一般会要求选择游戏目录或初始化数据目录。这里要留意它到底把数据放在哪个位置，因为后续导入整合包、模组、光影包都依赖这个位置。
如果客户端内置了版本下载功能，可以直接在版本列表里选择 Minecraft Java 版 26.x，等待下载完成。如果客户端没有内置下载，或者下载速度很慢，就需要手动导入游戏本体。
3.2 放置游戏本体与版本目录
手动导入游戏本体时，关键是把版本文件放到正确目录。一个常见的目录结构如下：
Amethyst/ ├── versions/ │ └── 1.26.x/ │ ├── 1.26.x.json │ └── 1.26.x.jar ├── libraries/ ├── mods/ ├── resourcepacks/ ├── shaderpacks/ ├── config/ └── logs/这里的versions/1.26.x/存放游戏版本元数据和 jar 文件，libraries/存放依赖库，mods/存放 Fabric/Forge 模组，shaderpacks/存放光影包，logs/存放运行日志。
不同客户端实际的目录名可能会不一样。有些工具会把游戏目录直接放在 App 的 Documents 里，有些会放在 Library/Application Support 下。最稳妥的做法是先通过文件 App 浏览 Amethyst 的目录结构，确认mods和shaderpacks到底在哪里，再决定往哪里放。
3.3 原版验证：这是后续一切排错的基准
安装完游戏本体后，先不要急着放 Fabric、Iris 和整合包。直接启动原版 Minecraft Java 版 26.x，创建一个新的单人世界，确认可以正常进入游戏、移动视角、放置方块。
这一步非常关键。因为如果此时就闪退，问题大概率集中在三处：
- 游戏版本文件不完整。
- 设备缺少必要的运行依赖。
- iOS 系统版本或硬件不满足最低要求。
在原版已经能跑通的基础上，再安装 Fabric 和 Iris。一旦后续出现问题，就能把排查范围缩小到“加载器或模组”，而不是整个游戏环境。
建议把“先原版、再加载器、最后模组光影”当作固定顺序。这个顺序适用于任何整合包，也适用于后续每次升级版本。
4. 安装 Fabric 和 Iris，搭好模组与光影的骨架
Minecraft Java 版的模组加载器有很多种，常见的有 Fabric、Forge、NeoForge、Quilt。Amethyst (Air) 这条主线里经常被放到一起的是 Fabric 和 Iris，因为它们配合紧密，而且在移动端上更轻量。
4.1 为什么选 Fabric 而不是 Forge
Fabric 和 Forge 都能加载模组，但设计思路不同。
| 对比项 | Fabric | Forge / NeoForge |
|---|---|---|
| 启动速度 | 更快，模块化加载 | 相对更重，初始化逻辑更多 |
| 新版本适配速度 | 通常更快，社区习惯跟进快照版 | 适配周期相对更慢 |
| 轻量模组支持 | 适合性能优化类和基础功能模组 | 适合大型内容模组和部分老牌整合包 |
| Iris 光影支持 | Iris 本身是 Fabric 系模组，集成最顺 | 需要额外处理兼容层，使用相对繁琐 |
| 移动端占用 | 更低，依赖更少 | 依赖较多，资源占用更高 |
在实际项目中，如果你是冲着“能跑 Fabric + Iris + 光影”这个目标来的，直接选 Fabric 会少很多兼容性问题。因为 Iris 的光影渲染后端与 Fabric 生态整合得最紧密，特别是在移动端上，减少不必要的依赖比功能强弱更重要。
4.2 选择和 26.x 匹配的 Fabric Loader
Fabric Loader 是启动模组的“引导器”，它本身不是模组。安装时需要注意三组版本：
- 游戏版本，例如
1.26.x。 - Fabric Loader 版本，例如
0.16.x或更高。 - Fabric API 版本，它必须和游戏版本对应。
安装时不要只下载“最新版”，要看它是否支持你的目标游戏小版本。下面是一个伪配置示例，用来理解版本组合关系：
{ "gameVersion": "1.26.x", "fabricLoader": "0.16.x", "fabricApi": "对应 1.26.x 的构建", "iris": "对应 1.26.x 的构建", "sodium": "对应 1.26.x 的构建" }在实际安装时，Fabric Loader 可能是一个安装器文件，也可能是 Amethyst 已经内置好的加载器选项。如果客户端里提供了加载器列表，优先选择与游戏版本明确匹配的那一项，不要选择“latest snapshot”或“latest release”这种模糊选项。
4.3 安装 Iris 与基础依赖
Iris 是一个光影模组，它的作用是让 Minecraft Java 版支持加载光影包（shaderpack），比如常用的 BSL、Complementary 等。Iris 并不单独工作，它通常需要依赖 Sodium 这个性能优化模组，因为 Sodium 重写了渲染管线，Iris 在其基础上实现光影加载。
安装方法非常简单：把iris.jar、sodium.jar、fabric-api.jar放到mods/目录里即可。但要注意，这三个 jar 的版本必须匹配同一个游戏版本，否则会出现模组互相拒绝加载的情况。
在移动端，不建议安装太多没有必要的模组。每多一个模组，启动时间和内存占用都会增加。对光影场景来说，Fabric Loader + Fabric API + Sodium + Iris 是最小闭环。
4.4 验证加载器是否生效
启动游戏后，不要只看是否进入主菜单，还要确认加载器确实被挂载。打开日志文件，或者留意启动输出中的关键信息。一个正常的 Fabric + Iris 启动日志会出现类似下面的内容：
[main/INFO]: Loading Minecraft 1.26.x [main/INFO]: Loading 4 mods: [main/INFO]: - fabric-api [main/INFO]: - fabricloader [main/INFO]: - sodium [main/INFO]: - iris [Render thread/INFO]: Backend library: Iris [Render thread/INFO]: Loading shaderpack: none如果在日志里看不到Loading mods这一段，说明模组目录没有生效，或者 jar 文件放错了位置。如果只看到 Fabric，却看不到 Iris，优先检查 Iris 版本是否支持当前游戏版本。
5. 安装整合包、模组和光影包
当 Fabric 和 Iris 已经能正常工作后，再进入资源安装阶段。整合包、模组、光影包是三种不同类型的资源，不能混在一起处理。
5.1 三类资源的区别
| 类型 | 文件后缀 | 作用 | 安装位置 |
|---|---|---|---|
| 整合包 | .mrpack、.zip | 把版本配置、模组、资源包、存档等打包在一起 | 通过客户端导入，或解压后手动放置 |
| 模组 | .jar | 改变游戏玩法或功能 | mods/目录 |
| 光影包 | .zip | 改变渲染效果、光照和画面风格 | shaderpacks/目录 |
常见误区是把.zip光影包直接解压后放到shaderpacks/目录，然后把文件夹也放进去了。正确的做法是让shaderpacks/下保持一个或多个“光影包文件夹”，每个光影包文件夹里是shaders目录和配置。例如：
shaderpacks/ ├── BSL_v8.x.zip ├── ComplementaryReimagined.zip └── 我的光影/ ├── shaders/ └── shaders.properties我的光影这种以文件夹形式存在的光影包也能被识别，但前提是文件夹内部结构正确。如果识别不到，优先检查是不是解压后多套了一层目录。
5.2 通过客户端导入整合包
Amethyst (Air) 如果支持直接导入整合包，操作方式通常是在文件 App 中长按整合包文件，选择“分享”，然后在应用列表里选择 Amethyst。导入后，客户端会解析整合包内的版本号、加载器类型和模组列表，自动完成放置。
导入完成后，回到版本列表或主界面，检查是否出现了整合包对应的版本。如果出现了，先看它的加载器是不是 Fabric。有些整合包基于 Forge 或 NeoForge，即使能被导入，也不能直接用本文的 Fabric + Iris 链路运行。
如果客户端不支持.mrpack格式，可以把整合包看作一个 zip 压缩包，手动解开，然后把里面的mods/、shaderpacks/、config/等目录合并到 Amethyst 对应目录。合并时不要直接删除原有目录，要按子目录逐层合并。
5.3 手动放置模组与光影包
手动安装时，文件要放到准确位置：
Amethyst/ ├── mods/ │ ├── fabric-api.jar │ ├── sodium.jar │ ├── iris.jar │ └── 其他模组.jar ├── resourcepacks/ └── shaderpacks/ ├── BSL.zip └── Complementary.zip注意几个常见问题：
- 模组文件必须是
.jar，不能是.zip改名。 - 同一个模组不要同时放两个版本，否则加载器会根据双方声明冲突或随机加载其中一个。
- 光影包必须是
.zip或一个完整文件夹，不能把 zip 解压后散放成多个文件。 - resourcepacks 是原版资源包，不能把模组 jar 放进去。
5.4 通过日志确认资源加载结果
安装完成后，启动游戏，打开日志或“模组列表”页面，确认三件事：
- 模组列表里出现
fabric-api、sodium、iris以及其他预期模组。 shaderpacks目录里的光影包能在游戏内被识别。- 启动过程中没有红色 ERROR 日志。
如果日志中出现类似下面的内容，说明某个模组版本不匹配：
[main/ERROR]: Mod iris requires version >=x.y of sodium, but found older version. [main/ERROR]: Incompatible mod set! Missing: fabric-api这类问题只能通过调整版本组合解决，不能通过删除日志或修改配置来绕过。建议回到第 4.2 节，重新核对 Fabric Loader、Fabric API、Iris、Sodium 的版本。
6. 常见问题排查：从闪退、黑屏到发热卡顿
即使严格按照顺序操作，iOS 上运行 Java 版模组仍然会遇到各种问题。下面按“现象 -> 原因 -> 检查方式 -> 处理建议”展开。
6.1 点击启动就闪退
| 现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 启动游戏后立刻退出到主界面 | 游戏版本文件不完整 | 检查versions/1.26.x/下 json 和 jar 是否齐全 | 重新下载游戏本体，不要混用版本号 |
| 启动时黑屏几秒后退回桌面 | 加载器版本与游戏版本不匹配 | 查看崩溃日志中的版本号 | 换成与 26.x 完全匹配的 Fabric Loader |
| 加载到 Mojang 界面后闪退 | 内存不足或模组冲突 | 查看日志段是否有 OutOfMemory | 减少模组数量，适当降低渲染距离 |
| 安装客户端后无法打开 | 描述文件未信任或过期 | 设置 > 通用 > 设备管理 | 重新信任描述文件，或重新获取安装包 |
排查时先看日志，不要反复重启。iOS 上虽然不像桌面端能直接打开控制台，但 App 内一般会有日志导出功能，或者logs/目录下的latest.log文件。如果你连日志都找不到，就把问题重点怀疑放在“安装包签名无效”上。
6.2 放进去的模组没有加载
模组没有出现在游戏内“模组列表”里，是移动端最常见的问题。
| 现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| mods 目录下能看到 jar，游戏里却没有 | 放到了错误目录 | 通过文件 App 确认路径是否在 Amethyst 的mods/下 | 把 jar 移动到客户端实际使用的目录 |
| 模组列表里有 Fabric 却看不到模组 | Fabric API 版本不匹配 | 查看日志中的 Missing 信息 | 下载与游戏版本匹配的 Fabric API |
| 所有 jar 都不显示 | 加载器没有安装 | 检查版本启动时是否有 Fabric Loader | 先安装 Fabric Loader，再放模组 |
| 只有部分模组不显示 | 某些模组依赖缺失 | 查看日志中 Missing dependency | 补齐前置模组，如 Sodium、Fabric API |
这里最容易忽略的是 iOS 文件 App 的多级目录。导入文件时，系统可能自动生成On My iPhone/Amethyst/mods，但客户端实际读取的是沙盒内部路径。遇到模组不加载，永远先确认路径，再检查版本。
6.3 Iris 光影加载异常
| 现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 游戏内没有“光影”按钮 | Iris 没有加载成功 | 查看日志能否看到 Backend library: Iris | 重新安装匹配版本的 Iris，确认它在 mods 目录内 |
| 选择光影后画面变黑 | 光影包与版本不兼容 | 换一个已知兼容的光影包 | 先加载默认光影测试，再换高配光影 |
| 光影开启后帧率骤降 | 设备 GPU 压力过大 | 查看温度、帧率 | 降低渲染距离、关闭水面反射、限制帧率 |
| 光影包在列表里看不到 | 目录结构错误 | 检查shaderpacks/下的 zip 或文件夹结构 | 重新打包光影包，避免多套一层目录 |
判断 Iris 是否生效，最直接的方法是进入游戏设置，看是否出现“光影...”按钮。没有这个按钮，无论往shaderpacks/里放多少 zip 都不会有反应。
6.4 帧率、发热和耗电问题
移动端运行 Java 版模组和光影，核心瓶颈是散热和功耗。即使设备跑得动电脑上的配置，iOS 上也可能因为机身温度过高而强制降频。
| 场景 | 推荐设置 | 说明 |
|---|---|---|
| 普通原版 | 渲染距离 12 到 16 区块 | 避免过远的区块加载 |
| 开启 Fabric 基础模组 | 渲染距离 8 到 12 区块 | 模组会额外增加内存占用 |
| 开启光影 | 渲染距离 8 区块以内 | 光影对 GPU 压力远大于原版渲染 |
| 设备发热严重 | 开启垂直同步或锁 30 帧 | 稳定帧率比高帧率更适合移动端 |
遇到发热问题，不要一边充电一边长时间游戏。Amethyst (Air) 本质上是把 Java 版跑在移动端容器里，CPU 和 GPU 负载都会明显高于普通手机游戏。建议在比较凉爽的环境下运行，同时关闭后台过多的 App。
6.5 可复用的排错清单
按这个顺序排查，能覆盖绝大多数问题：
- 原版 26.x 是否能启动？
- Fabric Loader 是否安装？
- Fabric API 是否与游戏版本匹配？
- Iris 和 Sodium 是否在 mods 目录下？
- 模组 jar 是否全部放在正确目录？
- 光影包是否放在 shaderpacks 目录且结构正确？
- 日志中是否出现 ERROR 或 Missing 关键字？
- 设备剩余空间是否充足？
- 描述文件是否已信任且未过期？
- 是否同时存在同一个模组的多版本 jar？
借助这份清单，可以快速判断问题出在“游戏环境”“加载器”还是“资源文件”三层中的哪一层。
7. 从“能玩”到“可维护”：备份、记录和扩展
Amethyst (Air) 环境跑通后，不要急着加一大堆模组。iOS 端重新配置环境的成本比电脑更高，一旦目录损坏或版本冲突，恢复会比较耗时。所以从第一次成功启动开始，就要养成记录和备份的习惯。
7.1 记录版本组合与存档
建议用一张表记录每次成功运行的版本组合。下面是一个示例：
| 组件 | 版本 | 备注 |
|---|---|---|
| iOS/iPadOS | 18.x | 设备系统版本 |
| Amethyst (Air) | 客户端版本 | 安装包来源 |
| Minecraft Java 版 | 1.26.x | 具体小版本 |
| Fabric Loader | 0.16.x | 与游戏版本匹配 |
| Fabric API | 对应版本 | 与游戏版本匹配 |
| Iris | 对应版本 | 与游戏版本匹配 |
| Sodium | 对应版本 | 与 Iris 配合 |
| 光影包 | BSL / Complementary | 版本号 |
| 关键模组 | 模组名称 + 版本 | 只记录必要的 |
以后每次更新版本，先看这张表，别盲目点击“全部最新版”。
7.2 目录备份与恢复
在稳定运行后，可以定期将 Amethyst 数据目录里的关键内容导出到 iCloud 或外部存储：
mods/目录：所有模组 jar。shaderpacks/目录：光影包。config/目录：模组配置。saves/目录：存档文件。
备份时不要只备份整个 App 的安装包，因为卸载重装后沙盒数据会被清除，备份文件需要能单独恢复到客户端目录中。如果客户端支持“导入备份包”，优先使用这种格式，因为它会保留目录结构。
7.3 延伸学习：Fabric 模组开发与性能调优
玩通整合包之后，下一步可以往两个方向延伸。
第一个方向是“调整性能”。既然 Fabric、Sodium、Iris 已经在 iOS 上跑通，就可以继续研究渲染距离、实体数量、粒子效果和内存分配对帧率的影响。这会帮助你判断一台设备到底能承受多复杂的整合包。
第二个方向是“自己写 Fabric 模组”。在电脑上用 Gradle 构建 Fabric 模组项目，把生成的 jar 放到 Amethyst 的mods/目录里，然后回到 iOS 上验证。这个过程能让你更清楚模组加载器的依赖关系，也会反过来解释为什么版本不匹配会导致启动失败。
无论是继续玩整合包，还是开始研究模组开发，都建议保持一个原则：不要把版本组合搞成“不可复现的黑盒”。只要记录清楚，后续无论换设备还是换整合包，都能快速找回来。
