08 日志输出(log)

作者：王世豪　|　最后修改：2026-04-27

一、LuatOS 日志输出介绍

LuatOS 使用 log 核心库进行日志输出，通过 log 库可以输出不同等级的用户日志；

1.1 日志的等级（日志输出函数）

日志的等级指的是日志输出函数本身的级别：

debug：调试内容输出，为日志输出优先级第 4 等级，优先级最低；

info：信息输出，为日志输出优先级第 3 等级，仅比 debug 级别高；

warn：警告输出，为日志输出优先级第 2 等级；

error：错误输出，为日志输出优先级第 1 等级，级别最高；

注：LuatOS 默认日志等级是 debug，可以输出 debug 及以上等级的日志；

如：log.debug(PROJECT, "debug message")，debug 为 log 模块的函数，使用小写英文字母；

1.2 日志输出等级（日志过滤级别）

日志输出等级指的是通过 log.setLevel() 设置的过滤级别，用于控制哪些级别的日志会被实际输出：

SILENT： 静默所有日志，即禁止日志有任何内容输出；

DEBUG： 输出 debug 及以上级别的日志；

INFO： 输出 info 及以上级别的日志；

WARN： 输出 warn 及以上级别的日志；

ERROR： 输出 error 级别的日志；

如：log.setLevel("INFO")，INFO 作为 setLevel 函数的参数存在，使用大写英文字母；

1.3 重要区别

debug（小写）：指的是 log.debug() 函数，用于输出 debug 级别的日志内容；

DEBUG（大写）：指的是 log.setLevel("DEBUG") 参数，用于设置输出 debug 及以上级别的日志；

其他级别（info/INFO、warn/WARN、error/ERROR）同理；

使用过程要注意大小写的区别，它们在不同的上下文中具有不同的作用；

1.4 使用关系

日志输出等级决定了哪些日志等级的日志会被实际输出：

当设置 log.setLevel("INFO") 时：

log.debug() 的日志不会被输出（因为 debug < info）
log.info()、log.warn()、log.error() 的日志会被输出

当设置 log.setLevel("ERROR") 时：

只有 log.error() 的日志会被输出
log.debug()、log.info()、log.warn() 的日志不会被输出

二、演示功能概述

本文使用 Air1601开发板，输出不同日志等级，以便开发者能快速了解日志功能的使用。

三、准备硬件环境

1、Air1601开发板一块

2、TYPE-C USB数据线一根

3、Air1601开发板和数据线的硬件接线方式为

Air1601开发板通过TYPE-C USB口连接TYPE-C USB 数据线，数据线的另外一端连接电脑的USB口；
在 Air1601 开发板上丝印标注 USB1，为芯片烧录下载接口；
若遇到因电脑 USB 端口供电不足导致的烧录失败，也可改用外部稳压电源通过开发板上的 VIN 引脚进行供电；

购买链接：Air1601开发板多功能5寸RGB屏支持AirUI 摄像头代开发固件-淘宝网

四、准备软件环境

4.1 软件环境

烧录工具：Luatools 下载调试工具；
内核固件文件（底层 core 固件文件）：

本demo开发测试时使用的固件为Air6101 V1012 版本固件，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试。

.luatos 需要的脚本和资源文件
脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air1601_Air1602/demo/log
LuatOS 运行所需要的 lib 文件：使用 Luatools 烧录时，勾选添加默认 lib 选项，使用默认 lib 脚本文件。

准备好软件环境之后，接下来查看如何烧录项目文件到 Air1601开发板中，将本篇文章中演示使用的项目文件烧录到 Air1601开发板中。

4.2 API 介绍

log 库：https://docs.openluat.com/osapi/core/log/

五、程序结构

log/
├── main.lua
├── log_test.lua
|── readme.md

5.1 文件说明

main.lua：主程序入口文件。
log_test.lua：演示不同日志输出等级的示例代码。

六、代码详解

6.1 main.lua

主程序文件 main.lua 是整个项目的入口点。它负责初始化系统环境。

6.2 log_test.lua

--[[
@module  log_test
@summary log功能测试模块
@version 1.0
@date    2025.10.25
@author  王世豪
@usage
本demo演示的核心功能为：
1. log.debug 日志等级测试
2. log.info 日志等级测试
3. log.warn 日志等级测试
4. log.error 日志等级测试

]]

local function test_log_output(level_name)
    print(string.format("测试日志级别: %s", level_name))

    log.debug(PROJECT, "debug message") 
    log.info(PROJECT, "info message")
    log.warn(PROJECT, "warn message")
    log.error(PROJECT, "error message")
end

local function logtest_task()
    -- 打印当前默认日志输出等级
    local default_level = log.getLevel()
    print("日志功能测试开始")
    print(string.format("默认日志级别: %s", default_level))

    -- 实验1：使用默认日志输出等级测试
    test_log_output(default_level)

    -- 实验2：设置为INFO级别，只输出info及以上级别的日志
    log.setLevel("INFO")
    test_log_output("INFO")

    -- 实验3：设置为WARN级别，只输出warn及以上级别的日志
    log.setLevel("WARN")
    test_log_output("WARN")

    -- 实验4：设置为ERROR级别，只输出error级别的日志
    log.setLevel("ERROR")
    test_log_output("ERROR")

    -- 实验5：设置为SILENT级别，完全关闭日志输出
    log.setLevel("SILENT")
    test_log_output("SILENT")

    -- 实验6：恢复默认日志输出等级，验证日志输出恢复
    log.setLevel(default_level)
    print("恢复默认日志输出等级: " .. log.getLevel())

    -- 测试不同参数类型的日志输出
    log.info(PROJECT, "数值:", 123, "布尔值:", true, "表:", {name="test", value=456})
end

-- 启动测试任务
sys.taskInit(logtest_task)

七、运行结果展示

注：详细日志输出内容，在程序中有增强注释说明，请详细查看。

八、总结

至此，我们已使用 Air1601开发板验证了不同日志输出等级下的日志打印效果。