▒ 目录 ▒
-
- 一、文档版本说明
- [二、LuaJIT 可执行文件](#二、LuaJIT 可执行文件)
- [三、LuaJIT 扩展命令行选项](#三、LuaJIT 扩展命令行选项)
-
- [1. `-b[子选项] 输入 输出`：字节码处理工具](#1.
-b[子选项] 输入 输出：字节码处理工具) - [2. `-j 命令[=参数]`：JIT 控制与扩展模块](#2.
-j 命令[=参数]：JIT 控制与扩展模块) - [3. `-O[选项]`：JIT 优化策略控制](#3.
-O[选项]：JIT 优化策略控制)
- [1. `-b[子选项] 输入 输出`：字节码处理工具](#1.
- 四、实战场景组合示例
-
- [场景 1：生产环境部署优化](#场景 1：生产环境部署优化)
- [场景 2：JIT 编译问题调试](#场景 2：JIT 编译问题调试)
- [场景 3：静态嵌入字节码到应用](#场景 3：静态嵌入字节码到应用)
- 五、注意事项
- 参考资料
一、文档版本说明
本文档对应 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可查看简洁帮助：
bash
# 查看帮助信息
> 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文件
lua
print('hello')测试
bash
# 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，输出到文件）。
命令行示例
bash
# 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）已满足多数场景，高级用户可通过选项定制。
优化选项格式
- 级别设置 ：
-O0（关闭所有优化）、-O1/-O2/-O3（递增优化）； - 单个标志 ：
-O+flag（启用）、-O-flag（禁用）（如-O+cse启用公共子表达式消除）； - 参数调整 ：
-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 |
命令行示例
bash
# 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：生产环境部署优化
bash
# 1. 编译脚本为字节码（移除调试信息，减小体积）
luajit -b test.lua test.raw
# 2. 启用最高优化并限制机器码缓存
luajit -O3 -Omaxmcode=1024 test.raw场景 2：JIT 编译问题调试
bash
# 1. 查看字节码生成是否正常
luajit -bl test.lua > bytecode.log
# 2. 输出 JIT 编译详情，定位未优化代码
luajit -j v=3 -O3 test.lua > jit_debug.log场景 3：静态嵌入字节码到应用
bash
# 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 示例五、注意事项
- 字节码兼容性：不同 LuaJIT 版本的字节码可能不兼容，建议随应用分发对应版本的 LuaJIT；
- 优化权衡：
-O3可能引入极个别兼容性问题（如浮点精度），关键场景需测试验证； - Windows 特殊处理：生成
obj文件时需匹配编译器（MSVC/MinGW），否则链接失败； - GC64 模式：64 位系统默认启用，处理大于 4GB 内存时需确保
-X选项正确使用。
参考资料
官网命令行说明： https://luajit.org/running.html