模块: Module 加载器
约 1563 字大约 5 分钟
2026-03-19
构建固件和导入到JS
loader是一个内置 module，构建固件时不需要在 C++ 中 use 引入。
在JS中导入 loader module：
import * as loader from 'loader'import loader简介
Loader 模块加载器
提供模块加载相关的底层功能，包括同步导入模块、编译字节码、 获取当前文件路径等功能。通常不需要直接使用，除非需要动态加载模块。
示例：
import * as loader from "loader"
// 获取当前文件的完整路径
console.log(loader.__filename()) // 例如: "/app/main.js"
// 获取当前文件所在目录
console.log(loader.__dirname()) // 例如: "/app"
// 同步导入模块（相对于当前文件路径解析）
const utils = loader.importSync("./utils.js")
// 编译 JS 文件为字节码（.bin）
loader.compile("/app/main.js", "/app/main.js.bin")模块函数
函数 importSync
原型: importSync (moduleName:string)
同步导入模块
相对于当前文件路径同步加载并执行指定模块，返回模块的导出对象。 与 ES6 的动态 import() 不同，这是同步执行的。
示例：
import * as loader from "loader"
// 导入相对路径的模块
const config = loader.importSync("./config.js")
console.log(config.default)
// 导入内置模块
const fs = loader.importSync("fs")参数:
moduleName
类型string
参数说明模块名称或路径
异常:
- 找不到模块时抛出异常
返回值:
类型object
说明模块的导出对象（namespace）
函数 __filename
原型: __filename (stack:number=1)
获取当前文件的完整路径
返回调用此函数的 JavaScript 源文件的完整路径。 可用于获取当前正在执行的脚本文件位置。
示例：
import * as loader from "loader"
// 在 /app/main.js 中执行
console.log(loader.__filename()) // 输出: "/app/main.js"
// 获取上层调用者的文件路径
console.log(loader.__filename(2))参数:
stack
类型number
默认值1
参数说明调用栈层级，1 表示当前文件，2 表示调用者，以此类推
返回值:
类型string
说明文件的完整绝对路径
函数 __dirname
原型: __dirname (stack:number=1)
获取当前文件所在目录
返回调用此函数的 JavaScript 源文件所在的目录路径。 常用于构建相对于当前文件的资源路径。
示例：
import * as loader from "loader"
// 在 /app/main.js 中执行
console.log(loader.__dirname()) // 输出: "/app"
// 构建相对于当前文件的配置路径
const configPath = loader.__dirname() + "/config.json"参数:
stack
类型number
默认值1
参数说明调用栈层级，1 表示当前文件，2 表示调用者，以此类推
返回值:
类型string
说明文件所在目录的绝对路径
函数 compile
原型: compile (source:string, dist:string)
编译 JavaScript 文件为字节码
将 JavaScript 源文件编译为 QuickJS 字节码（.bin 文件）。 字节码文件加载速度更快，且可以保护源代码不被轻易查看。
支持的输出格式：
.bin- 纯字节码文件.js.bin- 带源码标记的字节码文件
示例：
import * as loader from "loader"
import * as fs from "fs"
// 编译为同名的 .bin 文件
loader.compile("/app/main.js")
// 生成: /app/main.js.bin
// 指定输出路径
loader.compile("/app/main.js", "/app/main.bin")
// 后续可以直接导入字节码文件
// import * as main from "/app/main.js.bin"参数:
source
类型string
参数说明源 JavaScript 文件路径
dist
类型string
参数说明输出字节码文件路径，默认为源文件路径 + ".bin"
异常:
- 读取源文件失败时抛出异常
- 写入目标文件失败时抛出异常
返回值:
类型undefined
函数 exportValue
原型: exportValue (moduleName:string, valueName:string, value:any)
向指定模块导出值
动态地向已加载的模块添加导出值。这通常用于 C++ 侧或 JS 侧运行时 向模块动态注入内容。
示例：
import * as loader from "loader"
// 向 "myModule" 模块导出名为 "version" 的值
loader.exportValue("myModule", "version", "1.0.0")
// 在其他地方导入使用
// import { version } from "myModule"
// console.log(version) // "1.0.0"参数:
moduleName
类型string
参数说明目标模块名称
valueName
类型string
参数说明要导出的变量名
value
类型any
参数说明要导出的值
异常:
- 模块不存在时抛出异常
- 导出失败时抛出异常
返回值:
类型undefined
函数 allModuleNames
原型: allModuleNames ()
获取所有已注册模块的名称列表
返回当前环境中所有已注册的内置模块名称数组。 包括通过 ModuleLoader 注册的所有原生模块。
示例：
import * as loader from "loader"
// 获取所有模块名称
const modules = loader.allModuleNames()
console.log(modules)
// 输出类似: ["fs", "gpio", "serial", "loader", "process", ...]
// 检查某个模块是否存在
if (modules.includes("wifi")) {
console.log("wifi 模块可用")
}返回值:
类型Array<string>
说明模块名称数组