🚀 安装
QCL 是整个秦淮生态的底座，应当最先安装。它没有任何硬依赖，装好它，QI/QS/QF/QSt 等玩法插件才能正常加载。
🧰 环境要求
| 项目 | 要求 | 说明 |
|---|---|---|
| 服务端 | Paper / Purpur / Spigot 1.21.11+ | ⚠️ 强烈建议 Paper / Purpur，原因见下 |
| Java | 25+ | Purpur 26.1 需要 JDK25 |
| MC 版本 | 1.21.11+ | 低于此版本启动会被禁用 |
| Kotlin（运行时） | 2.3.0 | 由 libraries 段自动拉取，无需手动装 |
✅ QCL 无硬依赖，可以直接放进
plugins/启动。
⚠️ 为什么必须用 Paper / Purpur？（libraries 机制）
QCL 运行时需要 Kotlin、GraalJS、Groovy4 这些库。这些库不打包进 jar，而是写在 plugin.yml 的 libraries 段，由服务端在启动时从 Maven 自动下载并缓存到服务端的 libraries/ 目录。
- ✅ Paper / Purpur 原生支持
libraries自动拉取机制 → 一切正常。 - ❌ 纯 Spigot 不支持该机制 → Kotlin / GraalJS 可能加载失败，插件无法正常工作。
💡 结论：能用 Paper / Purpur 就别用纯 Spigot。这不是偏好，是 QCL 的运行库依赖此机制。
启动校验由 ServerCompat.validateServer() 负责：它会在启动时校验 Java ≥ 25 和 MC ≥ 1.21.11，不达标会打 severe 日志并禁用插件。
📦 安装步骤
1️⃣ 放入 jar
把 QinhCoreLib-1.2.0.jar 放进服务端的 plugins/ 目录。
服务端根目录/
├─ plugins/
│ └─ QinhCoreLib-1.2.0.jar ← 放这里
├─ libraries/ ← 运行库会自动缓存到这（Paper/Purpur）
└─ ...2️⃣ 启动服务端
第一次启动时，服务端会：
- 从 Maven 自动下载 Kotlin / GraalJS / Groovy4 到
libraries/（需联网，首次稍慢）； - 执行
ServerCompat.validateServer()校验 Java 与 MC 版本； - 自动生成 QCL 的配置与目录。
3️⃣ 自动生成的目录结构
启动成功后，会在 plugins/QinhCoreLib/ 下生成：
plugins/QinhCoreLib/
├─ config.yml # 主配置（含 modules: 段）
├─ guis/ # 自定义 GUI（YAML）
├─ scripts/ # 脚本（GraalJS / Groovy）
└─ data/ # 数据库 / 持久化数据📁 本系列文档里，YAML 与文件路径默认相对
plugins/QinhCoreLib/。
4️⃣ 验证安装
进服后执行：
/qcl status能看到生态状态摘要（平台状态、健康码、模块健康等），即安装成功。详细解读见 快速上手。
🪵 首次启动会看到什么日志？
QCL 的 onEnable 按以下顺序执行，正常情况下日志会反映这些阶段：
| 顺序 | 阶段 | 做了什么 |
|---|---|---|
| 1 | ServerCompat.validateServer | 校验 Java≥25、MC≥1.21.11 |
| 2 | StartupReporter.reset | 重置启动报告 |
| 3 | saveDefaultConfig | 释放默认 config.yml |
| 4 | 桥初始化 | EconomyBridge.init + QinhScriptBridge.init |
| 5 | 注册命令 | 用 Cloud 框架注册 /qcl |
| 6 | CustomGuiManager.init | 加载 guis/ 下所有 GUI |
| 7 | 模块加载 | 注册 22 个核心模块，按 priority 升序逐个 load()→enable() |
| 8 | 延迟 1 tick | 报告物品源可用性 + 加载 Groovy 外部物品模块 + 打印启动摘要 |
🧾 启动末尾的
StartupReporter.printSummary会打印一份启动摘要，这是确认是否一切正常的关键日志，建议每次重启都瞄一眼。
☕ Java 25 安装提示
QCL 要求 Java 25+（Purpur 26.1 需 JDK25）。如果你的服务器还在用 Java 17 / 21：
- 下载并安装 JDK 25（如 Temurin / Oracle JDK 25）；
- 修改服务端启动脚本，把
java指向 JDK25 的可执行文件，例如：bash"C:\path\to\jdk-25\bin\java.exe" -jar paper.jar nogui - 用
java -version确认输出为 25。
⚠️ 用低版本 Java 启动，QCL 会 severe 日志报错并自我禁用，整条生态都会瘫痪。
🔌 软依赖装在哪？
QCL 的软依赖（见 plugin.yml 的 softdepend）仅影响加载顺序，不强制。它们和普通插件一样放进 plugins/ 即可：
Vault · ExcellentEconomy · PlayerPoints · PlaceholderAPI · ModelEngine
CustomCrops · CustomFishing · MythicMobs · NeigeItems · MMOItems
CraftEngine · QinhItems · MagicGem · ItemsAdder · Nexo- ✅ 装了 → QCL 自动反射桥接，相应能力点亮。
- ❌ 没装 → 自动跳过，不报错，对应能力静默关闭。
软依赖只决定「谁先加载」，保证 QCL 在它们之后能正确桥接。具体对接见 03-外部插件对接。
🆘 常见安装失败
| 现象 / 日志 | 原因 | 解决 |
|---|---|---|
| Kotlin / GraalJS 加载失败、类找不到 | 用了纯 Spigot，不支持 libraries 自动拉取机制 | 换 Paper / Purpur |
| severe 日志提示 Java 版本不够，插件被禁用 | Java < 25 | 安装 JDK25 并改启动脚本 |
| severe 日志提示 MC 版本不够，插件被禁用 | MC < 1.21.11 | 升级服务端到 1.21.11+ |
| 首次启动卡在下载库 | 服务器无法访问 Maven | 检查网络 / 配置 Maven 镜像 |