【lua】luajit 命令行使用指南

一、文档版本说明

本文档对应 LuaJIT 2.1 版本（最新稳定版），不同版本的专属特性需参考对应 Git 分支下的 doc 目录。LuaJIT 2.1 相比 2.0 新增 GC64 模式、改进 JIT 优化策略及扩展 FFI 功能，是目前生产环境的首选版本。

二、LuaJIT 可执行文件

LuaJIT 采用单文件分发模式，不同系统的可执行文件如下：

• POSIX 系统（Linux/macOS/BSD 等）：luajit
• Windows 系统：luajit.exe

核心功能

• 直接运行 Lua 脚本或交互式执行代码（终端输入 luajit 进入交互模式）；
• 兼容标准 Lua 5.1 语法，支持多数 Lua 5.2/5.3 扩展特性；
• 基础命令行选项与标准 Lua 一致（如 -e 执行单行代码、-l 加载模块），执行 luajit -h 可查看简洁帮助：

  # 查看帮助信息> luajit -h
usage: luajit [options]... [script [args]...].
Available options are:-e chunk  Execute string 'chunk'.-l name   Require library 'name'.-b ...    Save or list bytecode.-j cmd    Perform LuaJIT control command.-O[opt]   Control LuaJIT optimizations.-i        Enter interactive mode after executing 'script'.-v        Show version information.-E        Ignore environment variables.--        Stop handling options.-         Execute stdin and stop handling options.

三、LuaJIT 扩展命令行选项

除标准 Lua 选项外，LuaJIT 新增以下核心功能选项，用于字节码处理、JIT 控制及优化调整。

1. -b[子选项] 输入 输出：字节码处理工具

用于编译、查看或导出 Lua 代码的字节码，支持跨平台移植，核心子选项如下：

子选项	功能说明
-l	仅列出字节码（不生成文件），用于调试代码生成逻辑
-s/-g	-s 移除调试信息（默认），-g 保留调试信息（含行号、局部变量名）
-W/-X	-W 生成 32 位字节码（非 GC64），-X 生成 64 位字节码（GC64 模式）
-d	确定性模式（相同输入生成相同字节码，忽略路径/时间等变量）
-n 名称	手动指定模块名（默认从输入文件名提取）
-t 类型	强制输出文件类型（如 raw/c/obj，默认按后缀自动识别）
-e 代码块	以字符串作为输入（如 -e "print('hello')"）
-（单减号）	用标准输入（stdin）作为输入，或标准输出（stdout）作为输出

输出文件类型（按后缀自动识别）

后缀	类型说明	典型用途
raw	原始字节码（可移植）	直接运行或通过 dofile() 加载
c/cc	C/C++ 源文件（字节码嵌入数组）	静态编译到应用程序中
h	C 头文件（静态字节码）	作为模块头文件供其他代码引用
obj/o	目标文件（与 OS/架构相关）	链接到二进制程序，减少加载时间

关键注意事项

• 原始字节码（raw）可跨平台运行，但需与目标 LuaJIT 版本兼容；
• 嵌入应用时，目标文件（obj/o）需与应用的编译架构一致（32/64 位）；
• Windows 下生成的 obj 文件需用 MSVC 链接，MinGW 生成的 o 文件需用 GCC 链接。

命令行示例（覆盖主流场景）

编写test.lua文件

print('hello')

测试

# 1. 基础用法：将脚本编译为可移植字节码
luajit -b test.lua test.raw  # 生成 raw 格式字节码
luajit test.raw              # 直接运行字节码文件，打印字符串 hello# 2. 保留调试信息（用于调试字节码对应的源码位置）
luajit -bg test.lua test_with_debug.raw# 3. 从命令行代码生成字节码
luajit -be "local x=10; print(x*2)" math.raw
luajit math.raw  # 输出：20# 4. 查看字节码（不生成文件）
luajit -bl test.lua  # 列出 test.lua 的字节码指令
luajit -bl test.raw
luajit -bl test_with_debug.raw  # 相比 test.raw 包含了文件名信息等# 5. 生成 C 源文件（用于嵌入应用）
luajit -b test.lua test_bytecode.c
# 生成的 .c 文件包含字节码数组，可通过 LuaJIT API 加载# 6. 跨架构生成字节码（如在 64 位系统生成 32 位字节码）
luajit -bW test.lua test_32bit.raw  # 32 位非 GC64 模式（windows下未成功执行）# 7. 标准输入/输出处理
cat test.lua | luajit -b - - > test_from_stdin.raw  # 从 stdin 读取，输出到 stdout

2. -j 命令[=参数]：JIT 控制与扩展模块

用于控制 JIT 编译器状态或加载扩展模块，命令优先匹配 jit.* 库函数，未匹配则加载 jit.<命令> 模块并调用其 start() 方法。

核心控制命令

命令	功能说明	示例
on/off	开启/关闭 JIT 编译器（默认开启）	luajit -j off test.lua（仅用解释器）
flush	清空 JIT 编译缓存（强制重新编译热点代码）	luajit -j flush test.lua
v	显示 JIT 编译过程详情（跟踪生成的机器码）	luajit -j v test.lua
dump	输出 JIT 各阶段中间代码（用于调试 LuaJIT 本身）	luajit -j dump=ir,asm test.lua
p	启动内置性能分析器（输出热点函数统计）	luajit -j p=profile.log test.lua

扩展模块参数说明

• -jv：通过参数控制输出详细程度，如 -j v=1（基础信息）、-j v=3（详细跟踪）；
• -jdump：指定输出阶段（ir 中间码、asm 机器码等），如 -j dump=ir,loop；
• -jp：分析器参数，如 -j p=1,file=prof.txt（采样间隔 1ms，输出到文件）。

命令行示例

# 1. 调试 JIT 编译过程（查看热点代码优化）
luajit -j v=2 test.lua  # 级别 2 输出，包含跟踪生成和退出信息# 2. 分析性能瓶颈（生成热点函数报告）
luajit -j p=5,file=profile.log test.lua
# 报告包含函数调用次数、耗时占比，用于定位性能问题# 3. 输出中间代码（调试代码未被 JIT 编译的原因）
luajit -j dump=ir,asm,exit test.lua > jit_dump.txt
# 查看 jit_dump.txt 可分析哪些代码未被优化，是否存在无法 JIT 的语法# 4. 临时关闭 JIT 并测试解释器性能
luajit -j off test.lua  # 对比开启 JIT 时的性能差异，定位 JIT 优化效果

3. -O[选项]：JIT 优化策略控制

用于精细调整 JIT 编译器的优化行为，默认优化级别（-O3）已满足多数场景，高级用户可通过选项定制。

优化选项格式

1. 级别设置：-O0（关闭所有优化）、-O1/-O2/-O3（递增优化）；
2. 单个标志：-O+flag（启用）、-O-flag（禁用）（如 -O+cse 启用公共子表达式消除）；
3. 参数调整：-Oparam=value（如 -Ohotloop=100 调整热循环阈值）。

核心优化标志（默认启用状态）

标志	功能说明	-O1	-O2	-O3	适用场景
fold	常量折叠与表达式简化	✅	✅	✅	所有场景，基础优化
cse	公共子表达式消除	✅	✅	✅	计算密集型代码
dce	死代码消除	✅	✅	✅	分支较多的逻辑代码
loop	循环优化（代码提升、展开）	❌	✅	✅	循环次数多的代码
abc	数组边界检查消除	❌	❌	✅	安全的数组访问（无越界风险）
fma	融合乘加运算（提升浮点性能）	❌	❌	❌	科学计算、图形学

常用参数调整（默认值与用途）

参数名	默认值	功能说明	调整建议
hotloop	56	触发 JIT 编译的循环迭代次数	频繁调用的小循环可设为 30
maxmcode	512	机器码缓存总大小（KB）	大型程序可增至 1024 或 2048
sizemcode	32	单个机器码区域大小（KB）	64 位程序可增至 64

命令行示例

# 1. 基础优化级别设置
luajit -O3 test.lua  # 默认最高优化（推荐）
luajit -O0 test.lua  # 关闭所有优化（调试用）# 2. 定制优化标志（启用循环优化，禁用死存储消除）
luajit -O+loop,-dse test.lua# 3. 调整热循环阈值（适合快速迭代的小循环）
luajit -Ohotloop=30 test.lua  # 循环迭代 30 次即触发 JIT# 4. 增加机器码缓存（大型应用避免缓存溢出）
luajit -Omaxmcode=2048,sizemcode=64 big_app.lua# 5. 启用融合乘加（FMA）优化（科学计算场景）
luajit -O+fma math_intensive.lua

四、实战场景组合示例

场景 1：生产环境部署优化

# 1. 编译脚本为字节码（移除调试信息，减小体积）
luajit -b test.lua test.raw# 2. 启用最高优化并限制机器码缓存
luajit -O3 -Omaxmcode=1024 test.raw

场景 2：JIT 编译问题调试

# 1. 查看字节码生成是否正常
luajit -bl test.lua > bytecode.log# 2. 输出 JIT 编译详情，定位未优化代码
luajit -j v=3 -O3 test.lua > jit_debug.log

场景 3：静态嵌入字节码到应用

# 1. 生成 C 源文件（含字节码）
luajit -b test.lua test_bytecode.c# 2. 编译时将 test_bytecode.c 与应用代码链接
gcc app.c test_bytecode.c -lluajit-5.1 -o app  # Linux 示例
cl app.c test_bytecode.c luajit.lib  # Windows MSVC 示例

五、注意事项

1. 字节码兼容性：不同 LuaJIT 版本的字节码可能不兼容，建议随应用分发对应版本的 LuaJIT；
2. 优化权衡：-O3 可能引入极个别兼容性问题（如浮点精度），关键场景需测试验证；
3. Windows 特殊处理：生成 obj 文件时需匹配编译器（MSVC/MinGW），否则链接失败；
4. GC64 模式：64 位系统默认启用，处理大于 4GB 内存时需确保 -X 选项正确使用。

参考资料

官网命令行说明： https://luajit.org/running.html