跳到主要内容

控制台日志

浏览器开发者控制台是调试 PlayCanvas 脚本最基础且不可缺少的工具。现代浏览器均内置开发者工具，控制台用于查看日志、错误，以及理解代码背后的执行过程。

什么是控制台？​

控制台是开发者工具中的命令行界面，可以：

  • 显示日志：从 JavaScript 直接输出消息、变量值和对象状态。
  • 显示错误和警告：查看 JavaScript 错误、引擎警告及主动记录的错误消息，通常附带调用栈，方便定位来源。
  • 交互检查：直接执行 JavaScript，检查运行中应用的状态，适合更深入的调试。

打开控制台​

不同浏览器的打开方式不同，常用方法有：

  • 快捷键：Windows/Linux 上按 F12；macOS 上，Chrome、Edge、Firefox 可使用 Option + Command + J（⌥ + ⌘ + J）。Safari 使用 Option + Command + C（⌥ + ⌘ + C），可能需要先在 Preferences > Advanced > Show Develop menu in menu bar 中启用 Develop 菜单。
  • 右键菜单：在运行中的 PlayCanvas 应用页面上右键，选择 Inspect 或 Inspect Element，再切换到 Console 标签页。
  • 浏览器菜单：在主菜单中寻找 Developer Tools、Web Developer 等选项，例如 Chrome 的 More Tools > Developer Tools。

从脚本输出日志​

JavaScript 的全局 console 对象是向控制台发送信息的主要方式。通常在 PlayCanvas 的 initialize、update 或事件处理函数中调用。

console.log()​

最常见的方法，用于一般信息输出。

  • 用途：记录状态消息、变量值，或检查函数是否被调用。

示例：

import { Script, KEY_SPACE } from 'playcanvas';

export class MyLogger extends Script {
    static scriptName = 'myLogger';

    initialize() {
        console.log('MyLogger script initialized on entity:', this.entity.name);
        const initialPosition = this.entity.getPosition();
        console.log('Initial Position:', initialPosition.toString());
    }

    update(dt) {
        if (this.app.keyboard.wasPressed(KEY_SPACE)) {
            console.log('Spacebar pressed!');
        }
    }
}

console.warn()​

用于表示潜在问题，或尚未构成错误但可能不符合预期的情况。

  • 用途：提示非关键问题、已弃用 API 的用法或可疑数值。
  • 外观：控制台中通常带黄色背景或图标。

示例：

// Inside some function
if (speed < 0) {
    console.warn('Warning: Speed is negative (' + speed + '). Is this intentional?');
}

console.error()​

用于记录导致代码无法正确工作的实际错误，PlayCanvas 引擎错误也使用此方法。

  • 用途：报告逻辑错误、操作失败或严重故障。
  • 外观：通常带红色背景或图标，并附调用栈，显示发生错误前的函数调用序列。

示例：

initialize() {
    this.targetEntity = this.app.root.findByName('RequiredTarget');
    if (!this.targetEntity) {
        console.error('Critical Error: Could not find RequiredTarget entity! Disabling script.', this.entity.name);
        this.enabled = false; // Stop the script from running further
    }
}

其他方法​

  • console.info()：类似 console.log()，有时使用不同样式，例如 i 图标。
  • console.debug()：通常默认隐藏，适合不需要一直显示的详细调试消息。

输出不同数据类型​

不仅可以输出字符串：

  • 变量：console.log('Player health:', this.health);
  • 对象和数组：console.log('My Entity:', this.entity);、console.log('Children:', this.entity.children);
    • 大多数浏览器控制台允许展开对象和数组，交互式查看属性和值，非常适合检查实体、组件或材质等复杂数据。

输出显示在哪里？​

无论通过编辑器的 Launch 按钮启动应用，还是运行已发布构建，日志都会显示在浏览器开发者控制台中，而非编辑器自身界面。测试时请保持开发者工具打开。

有效记录日志的建议​

  • 描述具体：不要只写 console.log('here');，应说明发生什么及相关数值，例如 console.log('Player jumped!', this.entity.getPosition());。
  • 提供上下文：尤其有多个脚本或实体时，应包含标识信息，例如 console.log(this.entity.name + ': Firing weapon.');。
  • 记录关键数值：在关键位置输出变量、函数参数和返回值，跟踪数据流。
  • 区分日志级别：合理使用 log、warn 和 error，让重要消息更醒目。
  • 按条件输出：通过 if 仅在特定情况发生时输出，减少刷屏。
  • 清理日志：完成代码前移除临时或过量的 console.log；可能以后需要、但平时不必显示的日志可使用 console.debug。

小结​

浏览器控制台是调试的第一步。掌握 console.log 及相关方法，可以大幅减少查找脚本异常原因的时间。请熟悉打开控制台、输出信息和分析结果的过程。