MSL 插件开发文档

Appearance

plugin_forceStopServer ​

强制终止 Minecraft 服务器进程。

函数签名 ​

javascript
plugin_forceStopServer(): void

参数说明 ​

此函数不接受任何参数。

返回值 ​

无返回值。

功能描述 ​

plugin_forceStopServer 用于强制终止 Minecraft 服务器进程。与正常执行 stop 指令不同，这个函数会直接杀死服务器进程，不会等待服务器保存数据或正常关闭。

这个函数通常在以下场景使用：

  • 服务器无响应（卡死）时强制关闭
  • 实现紧急停止功能
  • 在特定条件下需要立即终止服务器

警告

强制停止服务器可能导致数据丢失！服务器进程被强制终止时，可能无法完成世界保存操作。仅在紧急情况下使用此函数，正常情况下应使用 plugin_executeCommand("stop") 来安全关闭服务器。

使用示例 ​

基本用法 ​

javascript
// 强制停止服务器
plugin_forceStopServer();
plugin_log("WARN", "服务器进程已被强制终止");

紧急停止功能 ​

javascript
// 注册紧急停止指令
plugin_registerCommand("!emergency", (player) => {
    // 检查权限
    const admins = ["Steve", "Admin"];
    if (!admins.includes(player)) {
        plugin_executeCommand(`tellraw ${player} {"text":"权限不足","color":"red"}`);
        return;
    }
    
    plugin_log("WARN", `${player} 触发了紧急停止`);
    plugin_executeCommand("say 服务器即将强制关闭！");
    
    setTimeout(() => {
        plugin_forceStopServer();
    }, 3000);
});

服务器无响应检测 ​

javascript
// 检测服务器是否无响应
let lastLogTime = Date.now();
const TIMEOUT = 60000;  // 60秒无日志视为无响应

plugin_onEvent("serverLog", (line) => {
    lastLogTime = Date.now();
});

// 定期检查
setInterval(() => {
    const elapsed = Date.now() - lastLogTime;
    if (elapsed > TIMEOUT) {
        plugin_log("ERROR", "服务器可能无响应，执行强制停止");
        plugin_forceStopServer();
        
        // 5秒后重启
        setTimeout(() => {
            plugin_startServer();
        }, 5000);
    }
}, 30000);  // 每30秒检查一次

通过 HTTP API 紧急停止 ​

javascript
// 注册 HTTP API 用于远程强制停止
plugin_registerApi("POST", "/api/server/force-stop", (req, res) => {
    plugin_log("WARN", "通过 HTTP API 触发强制停止");
    plugin_forceStopServer();
    
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({
        success: true,
        message: "服务器进程已强制终止"
    }));
});

安全停止与强制停止对比 ​

javascript
// 安全停止（推荐）
function safeStop() {
    plugin_executeCommand("save-all");
    setTimeout(() => {
        plugin_executeCommand("stop");
    }, 5000);
}

// 强制停止（紧急情况）
function forceStop() {
    plugin_log("WARN", "执行强制停止，可能导致数据丢失！");
    plugin_forceStopServer();
}

// 根据情况选择停止方式
function stopServer(force = false) {
    if (force) {
        forceStop();
    } else {
        safeStop();
    }
}

平台差异 ​

MSL 在不同操作系统上使用不同的方式终止进程：

  • Windows：使用 taskkill /T /F /PID <pid> 命令
  • Linux/macOS：使用 SIGKILL 信号

注意事项 ​

  1. 数据安全：强制停止可能导致未保存的数据丢失
  2. 玩家断开：玩家会突然断开连接，不会显示正常的退出消息
  3. 世界损坏：极端情况下可能导致世界文件损坏
  4. 自动重启：如果配置了自动重启，服务器可能会在停止后自动重启

相关 API ​

相关事件 ​

  • serverStop - 服务器进程停止时触发（无论是正常停止还是强制停止）