JavaScript 问题排查指南

本文档将指导您掌握调试 JavaScript 问题的基本工作流程。

错误类型参考 ​

以下错误信息能帮助您调试代码，但有时报错原因并不直观。这些大多是 JavaScript 引擎中的常见错误，可通过搜索引擎（如 Google）查询解决方案。

点击每个错误名称下方的链接可查看 MDN 上关于该错误类的详细说明。

• EvalError
  • 表示与全局函数 eval() 相关的错误
• RangeError
  • 表示数值变量或参数超出有效范围时发生的错误
• ReferenceError
  • 表示引用无效时发生的错误。在 Minecraft 脚本引擎中，有时会出现无明显触发原因的引用错误：
  • 绑定到原型的原生对象不存在
• SyntaxError
  • 表示语法错误
• TypeError
  • 表示变量或参数类型无效时发生的错误
• URIError
  • 表示 encodeURI、encodeURI() 或 decodeURI、decodeURI() 传入无效参数时发生的错误
• AggregateError
  • 表示多个错误被包装为单个错误的情况，例如 Promise.any() 可能抛出此错误
• InternalError
  • 表示 JavaScript 引擎内部错误。在 Minecraft JS 中具体表现为：
    • 堆栈溢出
    • 内存不足

Minecraft 专属错误 ​

由于 Minecraft 基岩版使用基于 QuickJS 的自定义 JavaScript 版本，存在一些仅出现在 Minecraft 中的错误。这些错误较为常见，因为 API 构建在原生 C++ 之上。

InternalError: 内存不足 ​

当内存使用总量超过 250MB 时触发此错误。

这将导致看门狗机制终止运行并保存关闭世界，且无法通过 BeforeWatchdogTerminateEvent 取消。

可通过修改 server.properties 中的 script-watchdog-memory-limit 调整内存限制（设为 0 表示禁用限制）。

InternalError: 堆栈溢出 ​

当递归函数（调用自身的函数）缺少退出条件时发生。

示例代码：

function loop(x) {
  // 缺少基准条件
  loop(x + 1); // 递归调用
}
loop(0);
// InternalError: stack overflow

InternalError: 中断 ​

当运行时成本可忽略时触发，具体取决于脚本配置。

TypeError: 属性无设置方法 ​

尝试为只有 getter 的属性设置新值时触发。

常见于尝试设置原生模块中对象的属性时。

TypeError: 值不可迭代 ​

当尝试遍历非可迭代对象时触发。

点击此处了解更多。

TypeError: 非函数类型 ​

当尝试调用非函数类型的值时触发。由于脚本 API 经常未在更新日志中说明就移除或重命名方法，此错误十分常见。

点击此处了解更多。

TypeError: 原生类型转换失败 ​

当向原生方法的必填参数传入错误类型的值时触发。

TypeError: 原生变体类型转换失败 ​

当向原生方法的可选参数传入错误类型的值时触发。

TypeError: 对象缺少原生句柄 ​

当脚本尝试从 JavaScript 对象获取原生句柄，但该句柄实例已被清除时抛出。

ReferenceError: 绑定到原型的原生对象不存在 ​

当原生代码库因意外原因不支持某方法时抛出。某些情况下重启游戏可解决问题。

调试方法 ​

调试能帮助您准确定位 JavaScript 代码中的错误点。Minecraft 内置 JavaScript 调试器，可通过启用 设置 > 创作者 中的内容日志 GUI 来使用。

日志级别 ​

• [Scripting][Inform]

  使用 console.log() 或 console.info() 显示 JavaScript 值，但仅会记录在内容日志文件中。

  00:00:00-[Scripting][Inform]-：当使用 console.log() 或 console.info() 时触发

• [Scripting][Warning]

  在内容日志 GUI 和日志文件中同时输出警告信息。

  00:00:00-[Scripting][Warning]-：当使用 console.warn() 时触发

• [Scripting][Error]

  在内容日志 GUI 和日志文件中同时输出错误信息。

  00:00:00-[Scripting][Error]-：当使用 console.error() 时触发

堆栈追踪 ​

堆栈追踪是按顺序列出导致程序断点的函数列表，对定位代码问题根源非常有用。

示例：

[Scripting][error]-SyntaxError: unexpected character
    at <anonymous> (index.js:16)
    at parse (native)
    at r (bundle.js)
    at <anonymous> (bundle.js)

• 错误名称：SyntaxError
• 错误信息：unexpected character
• 错误源头：文件 index.js 第 16 行

原始出处