C++嵌入 Lua 脚本完整示例项目实战

因为这两个是独立可执行程序的入口（分别是解释器和编译器），我们是要做静态库供别人调用的，不需要这些'外壳'。如果你不小心加上去了，编译时可能会遇到类似这样的错误：

error LNK2019: unresolved external symbol _main referenced in function ...

没错，就是因为它试图找 main 函数！

排除掉之后，在项目属性里做几个关键设置：

• 配置类型 → 设置为'静态库 (.lib)'
• C/C++ → 运行库 → 根据主程序决定用 /MT 还是 /MD
• 预处理器定义 → 删除 LUA_BUILD_AS_DLL （否则会导出符号）
• 附加包含目录 → 指向 ../include ，方便后续使用

搞定之后点击生成，顺利的话你会看到输出：

正在创建库 D:\Projects\LuaInC++\lib\build_vs\Release\lua54.lib

可以用 dumpbin /symbols lua54.lib 验证一下是否包含了必要的符号，比如 lua_pcall 、 lua_getglobal 等。

💡 小贴士：建议把生成的 .lib 文件按平台分类存放，比如放在 lib/win32/lua54.lib ，这样以后做跨平台项目时结构更清晰。

Linux 环境下通过 Makefile 一键生成 liblua.a

转战 Linux 就简单多了，官方自带 Makefile 简直是贴心到家。

tar -zxvf lua-5.4.6.tar.gz
cd lua-5.4.6
make linux

一行命令搞定！成功后会在 src/ 下生成：

• liblua.a —— 我们需要的静态库
• lua —— 可执行解释器
• luac —— 字节码编译器

如果你想把它安装到系统路径，也可以：

sudo make install INSTALL_TOP=/usr/local

但这对嵌入式项目来说其实不太推荐，毕竟我们希望依赖尽可能封闭可控。更好的做法是在主项目的 Makefile 中自动拉取并构建：

LUA_SRC = ./thirdparty/lua-5.4.6
LUA_LIB = $(LUA_SRC)/src/liblua.a
$(LUA_LIB): $(MAKE) -C $(LUA_SRC) linux
%.o: %.cpp
g++ -c $< -o $@ -I$(LUA_SRC)/src -DLUA_USE_LINUX
main: $(LUA_LIB)
g++ main.o $(LUA_LIB) -lm -ldl -o main

看到了吗？这里有个容易忽略的点： 即使你是静态链接，也得加上 -lm -ldl 。因为 Lua 底层用了数学库和动态加载相关函数（比如 dlopen ），哪怕你自己没显式调用，编译器也会报'undefined reference'。

跨平台集成自动化流程

为了让这套机制更具通用性，我们可以画个 Mermaid 流程图来理清思路：

graph TD
A[下载 lua-5.4.6.tar.gz] --> B[解压至项目目录]
B --> C[进入 src/ 目录]
C --> D[执行 make linux]
D --> E[生成 liblua.a]
E --> F[拷贝至项目 lib/ 文件夹]
F --> G[C++ 项目链接 liblua.a]

这套流程最大的好处是什么？ 完全可控且可复现 。无论是本地开发还是 CI/CD 流水线，只要执行相同步骤，就能得到一致的结果。

接入 C++ 主程序

现在我们已经拿到了 .lib 或者 .a ，下一步就是让它真正'活'起来——接入我们的 C++ 主程序。

假设项目结构长这样：

LuaInC++/
├── include/ # 存放 lua.h, lualib.h 等
├── lib/
│   ├── win32/lua54.lib
│   └── linux/liblua.a
├── lua_scripts/
│   └── test.lua
├── src/
│   └── main.cpp
└── build/

在 Visual Studio 里，你需要设置三处关键路径：

1. C/C++ → 附加包含目录 → $(ProjectDir).. include
2. 链接器 → 附加库目录 → $(ProjectDir).. lib\win32
3. 链接器 → 附加依赖项 → lua54.lib

然后写一段最简单的测试代码：

extern "C" {
#include "lua.h"
#include "lualib.h"
#include "lauxlib.h"
}
#include <iostream>

int main() {
    lua_State* L = luaL_newstate();
    if (!L) {
        std::cerr << "Failed to create Lua state!" << std::endl;
        return -1;
    }
    std::cout << "Lua state created successfully!" << std::endl;
    luaL_openlibs(L);
    luaL_dostring(L, "print('Hello from Lua!')");
    lua_close(L);
    return 0;
}

如果一切正常，你应该能看到：

Lua state created successfully!
Hello from Lua!

🎉 成功了！但这只是万里长征第一步。

有几个坑我已经替你踩过了：

• 必须用 extern "C" 包住头文件，防止 C++ 名称修饰导致链接失败；
• 头文件顺序无所谓，但最好养成按 lua.h → lualib.h → lauxlib.h 的习惯；
• 如果出现 LNK2019: unresolved external symbol ，八成是库没连上或 MT/MD 不匹配。

说到 MT/MD，这是 Windows 下另一个著名'深坑'。

MT vs MD：运行时库冲突的那些事儿

你在 VS 里可能见过这四个选项：

• /MT ：多线程静态版
• /MTd ：调试版静态
• /MD ：多线程 DLL 版（发布推荐）
• /MDd ：调试版 DLL

问题来了： 主程序用 /MD ，Lua 库却用 /MT ，会发生什么？

答案是：堆空间分裂（heap split）。也就是说，你在 Lua 里 malloc 的内存，回到 C++ 这边 free 时可能出错，轻则崩溃，重则数据损坏。

怎么查？可以用：

dumpbin /directives lua54.lib

看看有没有 /failifmismatch:"RuntimeLibrary=MT_StaticRelease" 这种字样。

解决办法也很简单—— 保持一致就行 。要么全用 /MD ，要么全用 /MT 。我个人建议生产环境统一用 /MD ，这样可以减少最终二进制体积，并共享系统 CRT。

为了省事，还可以写个批处理脚本自动构建不同变体：

:: build_lua_md.bat
nmake /f Makefile.msc MYCFLAGS="-MD"

封装一层抽象

接下来我们玩点高级的—— 封装一层抽象，让跨平台变得更优雅 。

创建一个 lua_wrapper.h ：

#pragma once
#if defined(_WIN32) || defined(_WIN64)
#define PLATFORM_WINDOWS
#elif defined(__linux__)
#define PLATFORM_LINUX
#else
#error "Unsupported platform"
#endif

extern "C" {
#include "lua.h"
#include "lualib.h"
#include "lauxlib.h"
}

#ifdef PLATFORM_WINDOWS
#pragma comment(lib, "lua54.lib") // 自动链接
#endif

这样一来，主程序只需要 #include "lua_wrapper.h" ，连手动加依赖库都省了。是不是舒服多了？

再进一步，我们可以通过宏控制加载方式：

#define USE_LUA_STATIC_LIB // 或者定义 USE_LUA_SHARED_LIB

配合 CMake 之类的构建系统，就能实现全自动适配。

Lua 状态机的管理与数据交互

现在我们终于可以进入真正的核心环节了—— Lua 状态机的管理与数据交互 。

每一个 lua_State* 实例都是一个完全隔离的虚拟机环境。你可以把它理解为一个沙盒，里面有独立的栈、注册表、GC 机制和全局变量表。

创建很简单：

lua_State* L = luaL_newstate();
if (!L) {
    // 处理错误
}

但它背后的资源分配可不少：

• 栈空间（默认大小可通过 LUAI_MAXSTACK 调整）
• 字符串常量池
• 表结构哈希桶
• 垃圾回收器上下文

所以必须记住一点： 每次创建都要配对 lua_close(L) ，否则每运行一次就泄露几 MB 内存，很快就会 OOM。

聪明的做法是用 RAII 封装：

struct LuaDeleter {
    void operator()(lua_State* L) {
        if (L) lua_close(L);
    }
};
using LuaStatePtr = std::unique_ptr<lua_State, LuaDeleter>;
LuaStatePtr CreateLuaState() {
    return LuaStatePtr(luaL_newstate());
}

这样哪怕中途抛异常，也能自动释放资源，彻底告别内存泄漏。

标准库的安全加载

关于标准库的加载，这里有个重要提醒： 慎用 luaL_openlibs() ！

它一口气开了七个库，其中 io.* 和 os.* 危险系数极高。试想一下，如果用户脚本能执行 os.execute("rm -rf ~") ，你的服务器还能安稳吗？

所以更安全的做法是按需开启：

static const struct luaL_Reg loadedlibs[] = {
    {"_G", luaopen_base},
    {LUA_TABLIBNAME, luaopen_table},
    {LUA_STRLIBNAME, luaopen_string},
    {LUA_MATHLIBNAME, luaopen_math},
    {NULL, NULL}
};

然后逐个注册，排除 io 和 os 。甚至还可以进一步禁用 debug.getinfo 这类敏感函数。

对于不可信脚本，建议再加上沙箱环境：

local safe_env = {
    print = print,
    string = string,
    math = math
}
setmetatable(safe_env, {
    __index = function(_, k)
        error("Attempt to access forbidden global '" .. k .. "'", 2)
    end
})
_ENV = safe_env

双重防护，安心加倍。

执行模式与数据交互

执行 Lua 代码有两种模式，新手常混淆：

• luaL_dostring(L, code) ：简单粗暴，适合快速原型
• luaL_loadstring + lua_pcall ：分步执行，便于错误捕获

区别在哪？举个例子：

// 方式一：dostring
if (luaL_dostring(L, "syntax error")) {
    handle_error(lua_tostring(L, -1));
}
// 方式二：load+pcall
if (luaL_loadstring(L, "syntax error") == LUA_OK) {
    lua_pcall(L, 0, 0, 0);
} else {
    handle_compile_error(); // 可区分编译期错误
}

后者能精准定位问题是语法错误还是运行时异常，还能获取完整的栈回溯信息，更适合正式项目。

数据交互方面，核心就是那个'万能中介'—— Lua 栈 。

你想从 C++ 读取 Lua 变量？流程是：

lua_getglobal(L, "config_level"); // 把值压栈
if (lua_isnumber(L, -1)) {
    int level = lua_tointeger(L, -1);
}
lua_pop(L, 1); // 别忘了清理

反过来，往 Lua 传数据：

lua_pushinteger(L, 42);
lua_setglobal(L, "answer");

至于 C++ 对象传递， lightuserdata 虽然快，但风险也大——指针悬空、GC 失控、跨状态机无效等问题层出不穷。

推荐做法是用 full userdata + 元表：

void* ud = lua_newuserdata(L, sizeof(Person*));
*(Person**)ud = new Person("Alice", 25);
luaL_getmetatable(L, "PersonMeta");
lua_setmetatable(L, -2);

再配上 __gc 元方法，就能实现自动析构：

static int person_gc(lua_State* L) {
    Person* self = *(Person**)lua_touserdata(L, 1);
    delete self;
    return 0;
}

这才是工业级的做法。

C++ 类暴露给 Lua

最后，我们来看看如何把 C++ 类完整暴露给 Lua。

目标是让 Lua 脚本能这么写：

local p = Person.new("Bob", 20)
p:introduce()
p.age = 25
print(p.name)

实现思路分几步走：

1. 创建元表，设置 __index 拦截属性访问
2. 注册构造函数 new
3. 成员方法包装成 C 函数，通过 lua_touserdata 获取 this 指针
4. 添加 __gc 确保对象自动销毁

具体代码就不展开了（前面已有详细示例），但我想强调一点： 不要怕麻烦 。手工绑定确实繁琐，但换来的是极致的控制力和性能表现。

当然，如果你追求开发效率，也有像 Sol2 这样的现代 C++ 绑定库，只需几行模板代码就能完成自动注册：

sol::state lua;
lua.open_libraries();
lua.new_usertype<Person>(
    "Person",
    "new", sol::constructors<Person(std::string, int)>(),
    "name", &Person::name,
    "age", &Person::age,
    "introduce", &Person::introduce
);

一句话搞定！适合快速迭代的新项目。

总结

回顾整条技术链，你会发现 Lua 的强大之处不在于某一项炫酷功能，而在于它恰到好处地站在了'简洁'与'实用'的平衡点上。

它不像 Python 那样臃肿，也不像 JavaScript 那样难以嵌入。它的 API 干净利落，文档清晰明了，几乎没有多余的抽象层级。正因如此，才能在《王者荣耀》、《原神》这类顶级游戏中默默承担着核心逻辑调度的任务。

而当我们掌握了从环境配置、状态管理到类绑定的全套技能后，实际上已经具备了解决绝大多数嵌入式脚本需求的能力。

未来你可以继续探索的方向还有很多：

• 使用 Fengari 将 Lua 编译为 WebAssembly，在浏览器中运行；
• 结合 Redis 的 Lua 脚本引擎，打造高性能规则引擎；
• 基于协程实现异步任务调度系统……

但无论如何扩展，今天的这套基础框架都会是你最坚实的起点。

所以，下次当你面对'要不要加脚本系统'的争论时，不妨微笑着说一句：

'我已经准备好了。'