章节地图

三条最常见的查法

今天它占据哪些疆域

• 游戏脚本的事实标准：魔兽世界的整套插件 UI、Roblox 上的全部创作者逻辑；
• 高性能网关：OpenResty 用它写请求处理，Kong 整个构建在其上；
• 编辑器与数据库：Neovim 把它定为一等配置语言，Redis 用它实现原子操作。

版本年表与关键改动

一眼看出版本的三个探针

装与验

lua 命令行选项

luac 与环境变量

语法错误

调试手段

最常见的一条：attempt to index a nil value

• 意思是你在一个 nil 上取字段——t.config.debug 里如果 t.config 不存在，再取 .debug 就炸；
• 括号里会告诉你是哪个名字：(field 'config')、(global 'foo')、(local 'x')——先看这个提示，比看行号快。

八种类型

数值：整数与浮点

字符串：四种写法与转义

八种值，逐个认脸

Lua 动态类型：变量不带类型，类型属于值。共 8 种：

• nil 唯一值 nil，表示「无」
• boolean true / false
• number 含 integer 与 float 两个子类型
• string 不可变字节序列（8 位干净，可含 \0）
• function Lua 或 C 函数
• userdata 宿主 C 数据——full userdata 是 Lua 分配并受 GC 管理的一块内存（可带元表），light userdata 只是包了个裸 C 指针（无元表、不受 GC 管理）；纯 Lua 代码里几乎不会自己创建它们，只会从 C 库拿到（见 17 章）
• thread 协程
• table 唯一的数据结构：关联数组

八种里你日常真正会碰到的只有五种

• 「只有一种数据结构」是 Lua 最重要的一条设计：数组、字典、对象、类、模块、命名空间，全部由 table 承担。整个语言因此小得能塞进任何地方，代价是这些用法之间没有类型上的区分，靠约定；
• nil 兼职两个语义——「这个键没有」和「这个键的值是 nil」在 Lua 里是同一件事。所以表里存不了 nil，也就有了后面「数组中间的洞」那一系列坑。

作用域规则

• local 的作用域从声明的下一条语句开始，到所属块（do/函数体/循环体/if 分支）结束；
• 正因为「从下一条语句开始」，local x = x 是合法且常用的写法：右侧的 x 还是外层那个，等号左侧的新 x 尚未生效——这是把全局变量「抓」成局部的惯用法；
• 词法作用域意思是：一个函数能访问的外层变量，由它写在代码里的位置决定，而不是由谁调用它决定。被内层函数捕获的外层局部变量叫 upvalue（05 章闭包卡展开）。

全局变量到底存在哪

• 全局变量并不特殊，它们只是一张普通表的字段：这张表叫环境表，名字是 _ENV；
• 所以 x = 1 实际等价于 _ENV.x = 1，而 _G 就指向这张全局环境表；
• 这个设计的好处是环境可以被替换——把一段代码的 _ENV 换成你自己造的表，就得到了一个沙箱。完整机制见 12 章「_ENV 与沙箱」，现在知道「全局变量 = 一张表的字段」即可。

一个 number，两套表示

5.3 起 number 拆成两个子类型（默认均为 64 位），行为可预测又能自动转换：

• 3 / 2 → 1.5（/ 总产生 float）
• 7 // 2 → 3（// 向下取整，同类型进同类型出）
• 2 ^ 2 → 4.0（^ 总是 float）
• 整数溢出按二进制补码回绕

三种字面量

字符串不可变（修改即产生新串）。三种字面量：引号串、长括号串 [[ ]]（不转义、可跨行、忽略紧接的首个换行），以及 [=[ ]=] 用于内容含 ]] 的情形。

不可变意味着什么

• 「修改即产生新串」有一个直接的性能后果：循环里用 .. 累加字符串是 O(n²)——每次都要分配并拷贝一个新串。正确做法是把片段收进一张表，最后 table.concat 一次拼好；
• 好处是字符串可以被内部化（interning）：相同内容的短字符串在 Lua 里是同一个对象，所以 == 比较是 O(1) 的指针比较，做表的键也很快；
• 「8 位干净」的含义是字符串就是字节序列，可以含 \0——它不像 C 字符串那样以 0 结尾，因此能直接拿来装二进制数据（配 string.pack/unpack，16 章）；
• 长括号串 [[ ]] 有两个细节：不处理任何转义（写 Windows 路径、正则、HTML 片段时省心），以及忽略紧跟在开头的第一个换行（所以 [[ 后面可以直接换行，不会多出一个空行）。内容含 ]] 时升级成 [=[ ]=]，等号可以加任意多个。

一条规则

Lua 的假值（false values）只有 nil 和 false。其它一切——包括 0、""、{}——都为真。条件判断与 and/or 的求值都遵循此规则。

两种形态

行注释以 -- 起始；块注释用 --[[ ... ]]，内容含 ]] 时升级为 --[=[ ... ]=]。

块注释在哪收尾，是个真问题

• --[[ ... ]] 里如果出现 ]]（比如注释掉的代码里有 t[a[i]]），注释会提前结束，后面的内容变成语法错误；
• 解法是升级成 --[=[ ... ]=]，等号数量任意，只要与结尾配对；
• 一个流传很广的小技巧：--[[ 开头、--]] 结尾。这样在开头那行前面再加一个 - 变成 ---[[，整块就从「被注释」翻转成「生效」——两行都成了行注释；
• Lua 没有文档注释的语言级约定，社区惯例是 LDoc / LuaDoc 那套 --- 起头的格式。

算术

关系与逻辑

位运算（5.3 起）· 连接 · 长度

位运算在 LuaJIT（5.1 语法）上不存在，那边用 bit 库的函数（00 章版本表）。

除法的三个符号

• / 永远返回浮点数——7/2 是 3.5，4/2 也是 2.0 而不是 2；
• // 是向下取整除法（5.3 引入）：7//2 得 3；对负数是向下取整而非截断，-7//2 得 -4；
• % 取模，结果符号跟除数走：-7%3 得 2（不是 -1），这点和 C/Java 不同。

幂与其他

• ^ 是幂运算，总是返回浮点：2^10 得 1024.0；
• 整数除以整数用 // 才能保持整数类型，这在做索引计算时很要紧；
• 字符串会在算术场合自动转成数字："5" + 1 得 6——方便但也容易掩盖类型错误。

关系运算

• == ~=（不等号是 ~= 而非 !=）< > <= >=；
• 不同类型一律不相等，且不会自动转换："1" == 1 是 false；
• 表、函数按引用比较——两个内容相同的表 {1} == {1} 是 false（除非定义了 __eq，见 07 章）。

and / or 返回值而非布尔

• a and b：a 为假返回 a，否则返回 b；a or b：a 为真返回 a，否则返回 b；
• 两者都短路求值，右侧可能根本不执行；
• 由此得到 Lua 最常见的两个惯用法：默认值 local n = arg or 10，以及三元替代 cond and X or Y——后者有个陷阱，见下方 pitfall。

六个运算符

• & 与、| 或、~ 异或（放在两个操作数中间时是异或，放在前面是按位取反）、<< 左移、>> 右移；
• 操作数必须能无损转成整数，否则报错——1.5 & 1 会抛「number has no integer representation」；
• 移位是逻辑移位（补 0），不是算术移位；移动位数达到或超过 64 位时结果为 0（1 << 64 得到 0），不会像 C 那样是未定义行为。

.. 字符串连接

• 数字会自动转字符串参与拼接；nil 和布尔不会，拼它们直接报 attempt to concatenate a nil value；
• .. 两侧建议留空格：1..2 会被词法分析当成小数点而报错；
• 循环里反复 .. 拼接是 O(n²)——每次都新建字符串。拼大量文本请把片段放进表再 table.concat。

从高到低

优先级由低到高：

• or
• and
• < > <= >= ~= ==
• | → ~ → & → << >>
• ..（右结合）
• + -
• * / // %
• 一元：not # - ~
• ^（右结合，优先级高于一元）

条件与循环

遍历表：ipairs 还是 pairs

要「按顺序遍历字典」只能自己来：先把键收集进一个数组，table.sort 后再遍历（06 章）。

写法

• if 条件 then ... elseif 条件 then ... else ... end，用 elseif 一个词（写成 else if 会要求多一个 end）；
• 条件不需要括号，块结尾一律用 end；
• Lua 没有三元运算符，惯用 cond and X or Y 代替（陷阱见 03 章逻辑运算卡）。

while：先判断

• while 条件 do ... end，条件为假时退出；条件一开始就为假则一次都不执行。

repeat-until：后判断，且条件能看见块内变量

• repeat ... until 条件，至少执行一次，条件为真时退出（注意是 until，语义与 while 相反）；
• 关键特性：until 的条件表达式可以访问循环体里声明的 local——因为块的作用域延伸到了 until 之后。C 的 do-while 做不到这点；
• 这让「算出一个值再决定要不要继续」的写法很自然，不用把变量提到循环外面。

三个参数

• for i = 1, 10 do 跑 10 次（1 到 10，含 10），步长省略时为 1；
• 步长可以是负数：for i = 10, 1, -1 do 倒着数；步长为 0 会报错；
• 三个表达式只在循环开始前求值一次——循环体里改动它们引用的变量不会影响循环次数。

循环变量的性质

• i 是每轮新建的局部变量，作用域仅限循环体，循环结束后不存在；
• 因此在循环里创建闭包捕获 i 时，每轮捕获的是不同的变量（这点和早期 JS 的 var 相反，不会踩「所有闭包都拿到最后一个值」的坑）；
• Lua 5.5 起循环变量是只读的：在循环体里给 i 赋值会报 attempt to assign to const variable 'i'；5.4 及以前允许改（但改了也不影响循环推进）。

先记住两个常用的

• ipairs(t)：从 1 开始按整数下标遍历，遇到第一个 nil 就停——用来遍历「数组部分」；
• pairs(t)：遍历所有键值对，顺序不确定（哈希表本就无序，且同一份代码两次运行顺序可能不同）；
• 所以：要有序就用 ipairs 或数值 for；要全量就用 pairs，但别依赖它的顺序。

协议：explist 求出三个值

• for vars in explist do 中的 explist 会求出迭代函数、状态、控制变量初值三个值（5.4 起还可有第四个「关闭值」，属 <close> 范畴，见 10 章）；
• 每轮以 (状态, 控制变量) 调用迭代函数，返回值赋给循环变量；第一个返回值为 nil 时循环结束；
• 所以 pairs(t) 其实就是返回了 next, t, nil 这三个值——自己写迭代器也只要返回这样一组即可。

break

• 跳出最内层循环，Lua 没有带标签的 break；
• 要跳出多层循环，用 goto 跳到外层循环之后的标签。

goto 与 label（5.2 引入）

• 语法是 goto 名字 和 ::名字::；
• 最主要的用途就是模拟 continue：在循环体末尾放一个 ::continue:: 标签，需要跳过本轮时 goto continue；
• 限制：只能在同一函数内跳转，且不能跳进某个局部变量的作用域（否则那个变量会处于未初始化状态）——这条限制正是 Lua 敢开放 goto 的原因。

五种定义写法

变参与工具函数

闭包与尾调用

函数就是值

• function f() end 只是 f = function() end 的语法糖——函数没有「名字」，名字属于变量；
• 所以 local function f() 定义的是局部函数（且能递归调用自己，因为 local 先声明再赋值）；
• 写在表里就成了「模块」和「方法」：function M.foo()、function obj:bar()，本质都是往表里塞一个函数值。

调用的两处语法糖

• 单个字符串或表字面量作参数时可省略括号：require "mod"、f{1,2}——标准库和很多 DSL 大量使用这个写法；
• 参数个数不匹配不报错：多传的丢弃，少传的补 nil。这很灵活，但也意味着打错参数个数不会有任何提示。

多返回值的截断规则

• 在表达式列表的最后一个位置，多返回值会全部展开；
• 在其他任何位置，只保留第一个值：print(f(), 1) 里 f 只贡献一个值，print(1, f()) 才全展开；
• 加一层括号会强制只取第一个：(f()) 永远是单值——这是个刻意设计的「截断」写法。

接收与计数

• 多余的返回值被丢弃，不够的补 nil；用 _ 占位跳过不关心的返回值（_ 只是个普通变量名的约定）；
• select("#", ...) 数个数，select(n, ...) 取第 n 个之后的所有值；
• table.pack(...) 把变参装成表并带 n 字段，table.unpack(t) 反向展开——处理含 nil 的变参时必须用它们，原因见本章首卡的速查表。

基本用法

• 参数列表写 function f(a, ...)，函数体里用 ... 引用剩余参数；
• ... 遵守和多返回值一样的截断规则：只在最后位置才全部展开；
• Lua 5.5 起可以给它命名：function f(...args)（名字前没有逗号），得到一张带 n 字段的表（变量本身 const 不可重赋值，但表内容可改，Lua 5.5）——见 18 章。

捕获的是变量，不是值

• 闭包持有的是变量本身——外层函数已经返回了，那个局部变量依然活着，且闭包对它的修改是持久的；
• 所以闭包天然能做私有状态：把变量藏在外层函数里，只暴露操作它的闭包，外部无法直接访问（Lua 的对象封装常用这招）；
• 多个闭包捕获同一个变量时，它们共享同一份——这既是特性（协同修改）也是坑（意外共享）。

典型用途

• 计数器 / 累加器：把状态封在闭包里，不污染全局；
• 迭代器：闭包保存遍历位置，配合泛型 for 使用（见 04 章）；
• 回调与柯里化：预先绑定一部分参数，返回一个新函数。

什么算尾调用

• 必须是 return f(...) 这个精确形式：函数返回值直接就是另一个调用的返回值，中间不做任何加工；
• return f() + 1 不是尾调用（还要做加法）；return (f()) 也不是（括号是一次截断操作）；
• 满足条件时，当前函数的栈帧被复用而非新增——因此可以写无限深的递归而不会栈溢出。

代价

• 被复用的栈帧从调用栈上消失了，所以出错时的 traceback 会看到 (...tail calls...) 而非完整链路；
• 调试递归逻辑时这会让定位变难——这是拿可调试性换的无限递归能力。

冒号做了什么

• 定义时 function obj:m(a) 等价于 function obj.m(self, a)——冒号自动加了一个名为 self 的首参；
• 调用时 obj:m(1) 等价于 obj.m(obj, 1)——冒号自动把点号左边的对象作为首参传入；
• 两处的糖是对称的，所以定义和调用必须都用冒号，或都用点号并手写 self。

构造与访问

table 库

一张表，两个部分

• 表内部同时维护数组部分（连续整数键）和哈希部分（其余键），由实现自动选择，你不用管；
• 键可以是除 nil 和 NaN 外的任意值——字符串、数字、布尔、甚至另一张表或函数都能当键；
• 把某个键赋成 nil 就是删除它；读不存在的键返回 nil 而不报错。

构造与访问的写法

• {1, 2, 3} 数组式（自动编号 从 1 开始）；{x = 1} 记录式；{["复杂 key"] = 1} 显式键式，三者可混用；
• t.name 是 t["name"] 的语法糖——仅当键是合法标识符时可用点号；
• 键 1（数字）和 "1"（字符串）是两个不同的键，这点常被忽略。

怎么避免

• 删中间元素用 table.remove(t, i)（它会把后面的元素前移，保持序列），不要直接 t[i] = nil；
• 需要「可能有空位」的集合时，别依赖 #，改用显式计数字段，或用 pairs 遍历；
• 变参装表同理——用 table.pack(...) 拿它的 n 字段，而不是 #{...}。

序列上的工具

• table.insert(t, [pos,] v) · table.remove(t, [pos])
• table.concat(t, sep, i, j) 拼接序列
• table.sort(t, cmp) 原地排序
• table.pack(...) → 带 .n 的表；table.unpack(t, i, j)
• table.move(a1, f, e, t, a2) 批量搬移（5.3+）
• table.create(nseq [, nrec]) 预分配（5.5）

三个直接后果

• 赋值不复制：local b = a 之后 b[1] = 99，a[1] 也变成 99——两个名字指着同一张表；
• 传参不复制：函数内修改传入的表，调用方看得到（这是 Lua 里「输出参数」的常见做法）；
• 比较比的是身份：{1} == {1} 是 false，因为是两张不同的表。要按内容比较得自己写，或定义 __eq（见 07 章）。

需要副本时

• 浅拷贝：遍历 pairs 逐个赋值，或用 table.move——只复制一层，嵌套的表仍是共享的；
• 深拷贝：标准库没有，需要自己递归实现（注意处理循环引用）或用第三方库；
• 字符串则相反——它是不可变值类型，可以放心传递，改动总是产生新字符串。

装卸与查询

查找与赋值

运算与比较

二元运算的规则：先看左操作数有没有该元方法，没有再看右操作数。两边都没有才报 attempt to perform arithmetic。

两个拦截点

setmetatable(t, mt) 绑定元表。__index（表或函数）在读取缺失键时触发；__newindex（表或函数）在写入不存在的键时触发。已存在的键读写不触发。

触发条件：只在「缺失」时

local n = 0
local t = setmetatable({a = 1}, {__index = function() n = n + 1; return 0 end})
local _ = t.a    -- a 存在 → 不触发
local _ = t.b    -- b 缺失   → 触发
print(n)  --> 1

-- __newindex 同理
proxy.x = 1      -- x 不存在 → 触发
proxy.x = 2      -- x 已存在 → 不触发

• 这条「只拦缺失」的规则是性能设计：正常读写不用付元表查找的代价，只有落空时才走慢路径；
• 也正因如此，写代理表时 __newindex 里必须用 rawset(t, k, v) 存值——直接写 t[k] = v 会再次触发自己，无限递归；
• 反过来，如果想让每次写入都被拦截，就不能把值存进本表：常见做法是本表永远空着，真实数据放在另一张影子表里。

__index 给表还是给函数

• 表形式更快（C 层直接查表，还能尾链下去）；函数形式更灵活但每次落空都要跑一次 Lua 函数；
• 08 章的「类」用的就是表形式——Class.__index = Class 让实例查不到的方法回落到类表，这是 Lua 面向对象的全部机制。

非数值参与运算时查元方法

非数值参与运算时查元方法：先查第一操作数，没有再查第二个。适合做向量/矩阵/大数等类型。

查找顺序：先第一操作数，再第二个

local a = setmetatable({}, {__add = function() return "A的__add" end})

a + 1   --> A的__add
1 + a   --> A的__add   ← 数字没有 __add，于是查第二操作数

• 这条规则让 vec + 1 与 1 + vec 都能工作，而你只需要写一个元方法；
• 代价是元方法里不能假定哪个参数是「自己」——写向量库时必须先判断两个参数各是什么类型，否则 1 + vec 会取错字段；
• 字符串是个特例：Lua 会先尝试把字符串转成数字（"1" + 1 得 2），转不了才查元方法。这条自动转换在 5.4 中仍然存在，但依赖它是坏习惯。

杂项行为的开关

• __eq：仅当两者同为表或同为 full userdata 且非原始相等时触发，结果转布尔
• __lt __le：< <=（> 由 < 反推）
• __call：让表像函数一样被调用
• __tostring：定制 tostring/print 输出
• __len：定制 #；__concat：定制 ..

#（长度）的两件事

#{1, 2, nil, 4}  --> 2（5.5 与 5.4 一致）
                 -- 但这是未定义行为：带洞表的 # 只保证返回某个边界

#setmetatable({}, {__len = function() return 99 end})  --> 99

• 带洞的表用 # 是本页最值得记住的一条禁忌——返回值取决于表的内部存储布局，换个 Lua 版本、甚至换个插入顺序都可能不同；
• 要长度可靠，就自己维护一个计数字段，或者保证序列里没有 nil；
• __len 能定制 #，但不影响 ipairs 与 table.* 的行为——它们各有自己的边界规则。

生命周期与保护

• __close：to-be-closed 变量离开作用域时调用（5.4+，见「变量属性」）
• __gc：对象被回收前的终结器
• __mode："k"/"v"/"kv" 弱键/弱值（见「内存与垃圾回收 · 弱表」）
• __name：错误信息/tostring 中显示的类型名
• __metatable：设置后 getmetatable 返回它、setmetatable 报错（保护）

五个各管一件事

• 要释放资源就用 __close，不要用 __gc：后者可能在几秒后、也可能在程序退出时才跑，文件句柄和锁等不起；
• __gc 还有个陷阱——元表必须在 setmetatable 时就已经含 __gc，事后往元表里补一个是无效的；
• __metatable 设了之后 getmetatable 返回它、setmetatable 直接报错，是给沙箱与库作者用的保护开关（12 章）。

最小类模板

继承：把 __index 串成链

三种风格对照

类表兼作元表

惯用模式：类表自己当元表，Class.__index = Class，实例方法查不到时回落到类表。

那两行样板各自在做什么

local Dog = {}
Dog.__index = Dog              -- ① 类表自己当「查不到时去哪找」
function Dog.new(name)
  return setmetatable({name = name}, Dog)   -- ② 实例的元表就是类表
end
function Dog:speak() return self.name .. " 汪" end

• ①和②合起来的效果：实例上找不到 speak → 查元表（Dog）的 __index → 又是 Dog → 找到方法。一张表同时扮演了「类」和「元表」两个角色，省掉一层间接；
• function Dog:speak() 的冒号是语法糖，等价于 function Dog.speak(self)；调用处 d:speak() 等价于 d.speak(d)——冒号只在「定义处和调用处都用」时才配对，混用是最常见的一处错误；
• Lua 里没有 class 关键字，所以这套约定不是唯一写法：闭包式（每个实例带一份方法）更封闭但更费内存，各种 OOP 库还有别的花样。读别人代码时先确认它用的是哪一套。

沿 __index 链多走一层

让子类表以父类为 __index，方法查找沿链上溯；子类可覆盖同名方法，并用 Parent.method(self, ...) 调用父类实现。

链有多长就能上溯多远

A.__index = A ; function A:who() return "A" end
B = setmetatable({}, {__index = A}) ; B.__index = B
C = setmetatable({}, {__index = B}) ; C.__index = C
setmetatable({}, C):who()  --> "A"   三层链一路上溯

• 每落空一次就要多走一层，继承层次深了会有实打实的查找成本——热点方法可以在子类里复制一份（C.who = A.who）把链压平；
• 没有 super 关键字：调父类实现要写 Parent.method(self, ...)，注意是点号加显式 self，写成 Parent:method(...) 会把 Parent 自己当成 self；
• 多重继承只能自己实现：把 __index 写成函数，依次去几个父类里找。但那样每次落空都要跑 Lua 函数，代价明显高于表形式。

抛出

捕获

警告与动态加载

两个抛错入口

error(obj [, level]) 抛错（错误对象可为任意值（含 nil）；字符串会自动加位置前缀，level 控制位置归属）。assert(v [, msg]) 在 v 为假时以 msg 抛错，否则原样返回参数。

level 决定错误信息指向谁

error("boom", 1)   --> lt.lua:49: boom   ← 默认，指向 error 这一行
error("boom", 0)   --> boom              ← 完全不加位置
error("boom", 2)   --> 指向调用者那一行

error({code = 42}) --> 错误对象是表，type 为 table，不加任何前缀

• level = 2 是写库时的正确选择：参数校验失败时，用户想看到的是「你调错了的那一行」，而不是库内部报错的那一行；
• 「字符串会自动加位置前缀」这条只对字符串成立——抛表、抛任意值时 Lua 一个字都不加，所以结构化错误对象需要自己记录位置；
• assert(v, msg) 是 if not v then error(msg) end 的快捷方式，但它原样返回全部参数（assert(1,2,3) 返回 1 2 3），所以能写成 local f = assert(io.open(...)) 这种一行式；
• 注意 assert 的第二个参数总会被求值——写 assert(x, "错误：" .. expensive()) 时那个拼接每次都会跑。

把「会不会炸」变成返回值

pcall(f, ...) 返回 ok, 结果或错误对象。xpcall(f, handler, ...) 在栈展开之前调用 handler（常用 debug.traceback 拿回溯）。

xpcall 存在的唯一理由：栈还在

• pcall 返回时栈已经展开了——你只拿到错误对象，现场没了；
• xpcall 的 handler 在栈展开之前被调用，所以此刻 debug.traceback 还能拿到完整回溯。把 handler 写成 function(m) return debug.traceback(m, 2) end 就能拿回「出错时的调用链」；
• 这也是为什么不能在 pcall 之后再去 debug.traceback——那时打印的是当前位置的栈，与出错点无关；
• 实务：库内部用 pcall，程序最外层与后台任务用 xpcall——后者出问题时你需要日志里有回溯。

不打断执行的通道

warn(msg, ...)（5.4 引入）输出警告但不中断程序。以 @ 开头的控制消息可开关：warn("@on") / warn("@off")。宿主还可从 C 侧定制警告的处理方式。

它的定位：介于 print 与 error 之间

• print 走 stdout、混在正常输出里；error 会中断流程。warn 走 stderr 且不中断——正好是「弃用提示、配置可疑、降级处理」这类消息该待的地方；
• 默认是关闭的：Lua 启动时警告系统处于 off 状态，要先 warn("@on") 才会输出。这是刻意的——嵌入 Lua 的宿主程序不该被脚本的警告刷屏；
• 以 @ 开头的消息是控制消息而非内容，宿主可以定义自己的控制字；C 侧用 lua_setwarnf 可以把警告接到宿主的日志系统里（17 章）；
• 多个参数会被拼接成一条警告（不像 print 用制表符分隔）——这是为了让控制消息能被完整识别。

字符串变函数

load(chunk [, chunkname [, mode [, env]]]) 把一段字符串（或读取函数）编译成一个函数（chunk）；编译失败不抛错，而是返回 nil 与错误信息（正好与 pcall 的成败协议呼应）。mode 限定 "t"（文本）/"b"（字节码）/"bt"，env 指定该 chunk 的 _ENV（即沙箱，见「模块与包 · _ENV 与沙箱」）。loadfile 同理但从文件读；string.dump 把函数反向序列化成字节码串。

失败不抛错，返回 nil + 消息

load("this is not lua")
--> nil    [string "this is not lua"]:1: syntax error near 'is'

load("return 1 + 1")()  --> 2

• 「编译失败返回 nil」的协议正好与 pcall 的 ok, err 同形，所以可以写成 local f = assert(load(src)) 一行搞定；
• mode 参数限定接受什么："t" 只接受文本、"b" 只接受字节码、"bt" 都行（默认）。加载不可信内容时必须传 "t"——恶意字节码能让解释器崩溃甚至更糟，Lua 的字节码校验器不是安全边界；
• 第四个参数 env 就是沙箱的入口（12 章）：给这段代码一张受控的全局表，它就看不到真正的 _G；
• string.dump 反向把函数序列化成字节码串——但字节码在大版本间不兼容（5.4 的 dump 在 5.5 上加载不了），别拿它做长期存储。

<const>

<close>：Lua 的 RAII

编译期只读绑定

local x <const> = expr 声明只读局部（5.4+）。任何后续赋值在编译期报错。编译器还能据此优化。5.5 起 global 声明也可带 <const>。

它拦的是绑定，不是值

load("local y <const> = 1; y = 2")
--> nil  [string "..."]:1: attempt to assign to const variable 'y'
     ↑ 编译期就报错，不是运行时

• 注意是绑定只读：local t <const> = {} 之后 t.x = 1 完全合法——锁住的是「t 指向谁」，不是表的内容。要内容只读得靠 __newindex（07 章）；
• 编译器据此可以优化：常量表达式会被直接内联，不再每次去取局部变量槽；
• 它还是 <close> 的前提——<close> 变量隐含 <const>，否则「离开作用域时关掉的到底是哪个对象」就说不清了；
• 5.5 起 global 声明也能带 <const>（18 章），用来把库函数声明成不可被覆盖的只读全局。

作用域结束就清理

local r <close> = obj：当 r 离开作用域（正常、break、return、错误）时，自动调用 obj 的 __close 元方法。obj 须为 nil/false 或带 __close。这是 Lua 的确定性清理机制。

四条退出路径都会触发

do
  local r <close> = setmetatable({}, {__close = function() print("[清理]") end})
  print("作用域内")
end
print("作用域外")

输出：作用域内 → [清理] → 作用域外

• 正常结束、break、return、抛错——四条路径全都会调 __close。出错路径也覆盖是它相对「函数末尾手动 close」的根本优势；
• 对比 __gc：那个要等 GC 心情好；<close> 是确定性的、立即的，这正是 RAII 的定义；
• 值必须是 nil、false 或带 __close 的对象——给个普通表会在声明处直接报错，而不是等到作用域结束才发现；
• 协程里挂着的 <close> 变量由 coroutine.close 负责触发（11 章）——否则一个永远不被 resume 完的协程会把资源攥到进程结束。

API 全表

值怎么在两边传

记法：resume 与 yield 是一对互相喂值的函数，谁先执行谁把值交给对方的返回位置。

四种状态

可暂停的函数

coroutine.create(f) 得到 thread；resume(co, ...) 启动/继续，参数传给 f 或作为 yield 的返回值；yield(...) 暂停并把值传回给 resume 方。协程是协作式的：只在 yield 处让出。

resume 与 yield 是双向传值

co = coroutine.create(function(a, b)
  print("协程收到", a, b)           -- 1  2   ← 来自第一次 resume
  local c = coroutine.yield(a + b)  --        ← 把 3 传回给 resume
  print("resume 传回", c)           -- 99     ← 来自第二次 resume
  return "done"
end)

resume(co, 1, 2)  --> true  3      status 变 suspended
resume(co, 99)    --> true  done   status 变 dead
resume(co)        --> false  cannot resume dead coroutine

• 四条通道要分清：第一次 resume 的参数 → 函数形参；yield 的参数 → resume 的返回值；后续 resume 的参数 → yield 的返回值；函数 return 的值 → 最后一次 resume 的返回值；
• resume 的第一个返回值是成功标志，语义与 pcall 一致——协程里抛的错不会炸掉调用方，而是变成 false, 错误对象；
• 「协作式」的含义：协程只在自己调 yield 时让出，没有抢占、没有时间片。所以一个死循环的协程会把整个程序卡死；
• 协程不是线程：同一时刻只有一个在跑，不存在数据竞争，也用不上锁。

把 resume 协议藏起来

coroutine.wrap(f) 返回一个函数，每次调用即 resume（出错则直接抛出，不返回 ok）。适合做惰性生成器。coroutine.status(co) → suspended/running/normal/dead。running()、isyieldable() 辅助判断。

create 与 wrap 的取舍

• wrap 生成器：local gen = coroutine.wrap(...) 之后连着调三次得 1 2 3——直接就能放进 for x in gen do，这是它最常见的用法；
• 代价是错误会穿透出来：生成器内部出错时你看到的是普通的运行时错误，而不是一个可检查的返回值。要兜住就得在外面包 pcall；
• status 的四个值里 normal 最容易被忽略——它表示「这个协程 resume 了别人，正在等」，只在嵌套协程里出现。

强制释放挂起的协程

coroutine.close(co)（5.4 引入）把挂起或出错的协程置为 dead，并运行其中未完成的 <close> 变量的 __close，确保资源释放。

它填的是哪个洞

• 一个协程 yield 在半路、之后再也没人 resume 它——它栈上那些 <close> 变量永远不会被触发，文件句柄、锁、连接就一直攥着；
• GC 最终会回收协程对象，但那是不确定的时机，而且 __gc 与 __close 是两回事；
• coroutine.close(co) 把它置为 dead 并立即跑完所有未完成的 __close，返回是否全部成功；
• 典型场景：迭代器提前 break、任务被取消、超时放弃。凡是「协程可能不被跑完」的地方，都该在收尾处调一次 close。

模块模板与 require

搜索路径

沙箱三件套

查找、加载、缓存

现代模块惯例：文件返回一张表，不污染全局。require("mod") 查找、加载、缓存结果（同名只执行一次），重复 require 返回同一份。

require 到底去哪找

• package.path Lua 模块搜索模式（? 替换为模块名）
• package.cpath C 扩展（.so/.dll）搜索模式
• package.loaded 已加载模块缓存表
• package.preload 预注册加载器
• package.searchers 搜索器列表（5.2 起，原名 loaders）

五张表，一条流水线

• 排查「找不到模块」的顺序：先打印 package.path 看模式对不对，再确认文件名与 require 的名字大小写一致（Linux 区分大小写，Windows 不区分——这是「我这能跑你那不行」的经典来源）；
• 模块名里的 . 会被替换成目录分隔符：require("a.b") 找的是 a/b.lua；
• package.preload 是把模块嵌进单个可执行文件的标准手段——嵌入式场景（17 章）里很常用。

全局只是一张表的字段

全局变量其实是环境表 _ENV 的字段：x ≡ _ENV.x，_G 指向默认全局环境。每个 chunk 都有自己的 _ENV upvalue。给 load 传第 4 个参数 env（见「错误处理 · 动态加载」），就能让被加载的代码跑在一张受控表里——看不到、也改不了真正的全局，这便是沙箱。

换一张表就是一个沙箱

local sandbox = {print = print, type = type}
local f = load("x = 1; return type(os)", "s", "t", sandbox)

f()               --> nil    ← 沙箱里根本没有 os
sandbox.x         --> 1      ← 写入落到了沙箱表里
真正的全局 x      --> nil    ← 一点没污染

• 机制极简：每个 chunk 有一个名叫 _ENV 的 upvalue，x 就是 _ENV.x 的语法糖。换掉 _ENV，这段代码眼中的整个世界就换了；
• 沙箱的安全性取决于你放进去什么：放了 load 就等于放弃了控制（它能再造环境），放了 string.rep 就可能被用来吃内存；
• 沙箱挡不住资源耗尽：死循环、无限分配都不受 _ENV 约束。真要防，得用 debug.sethook 设指令计数钩子强制中断；
• 另一条：string 的元表是全局共享的——沙箱里能拿到字符串就能拿到 ("").rep，进而摸到整个 string 库。要彻底隔离得连元表一起换。

生成可回读的源码

Lua 无内置序列化，但有个惯用法：把表转成一段可被 load 执行的 Lua 源码（通常形如 return {...}）存盘；读回时 load 那段源码即得回原表。配合「错误处理」章的 load 与本章的沙箱，构成配置文件、存档、进程间传数据的基础。

collectgarbage(opt) 全部选项

查泄漏的标准做法：collectgarbage() 完整回收一次，再 collectgarbage("count")。不先回收，读到的数字里混着一堆还没清的垃圾，看不出趋势。

弱表：__mode

两种模式

一个函数管所有 GC 操作

collectgarbage(opt, ...) 常用选项："collect" 整轮回收、"count" 用量（KB）、"step" 走一步、"stop"/"restart" 暂停/恢复、"incremental"/"generational" 切换模式。

常用选项各在什么时候用

• 量内存的标准姿势是「先 collect 再 count」：直接 count 量到的是「活对象 + 还没回收的垃圾」，两次测量之间的差值毫无意义；
• "stop" 不是免费的：暂停期间分配的对象一个都不回收，时间稍长就是内存暴涨。它只适合「这一小段绝对不能有停顿」的场景，用完立刻 restart。

让 GC 能收走缓存

元表 __mode 含 "k" 则键为弱引用，含 "v" 则值为弱引用。当某对象只被弱引用持有时，可被回收，对应条目自动移除。适合缓存、对象到元数据的映射。

只被弱引用持有的对象会消失

local weak = setmetatable({}, {__mode = "v"})
do local tmp = {} ; weak[1] = tmp ; weak[2] = {} end
collectgarbage("collect")

weak[2]  --> nil    ← 只有弱表引用它，被回收，条目自动移除

• __mode 的三种取值："k" 弱键、"v" 弱值、"kv" 两边都弱；
• 选哪种取决于「谁决定生死」："k" 用于「对象活着时才需要它的元数据」（对象→附加信息的映射）；"v" 用于「别处还在用就留着」的缓存；
• 陷阱：字符串和数字不算「可回收对象」——用它们做弱键或弱值，条目永远不会被清掉。弱表只对表、函数、协程、full userdata 生效；
• 另一个陷阱：值里如果间接引用了键，弱键表就清不掉（键被值吊着）。这种情形要用ephemeron 表——Lua 5.2 起 __mode = "k" 已经实现了 ephemeron 语义，会正确处理这种循环。

两种模式各治一种停顿

分代 GC（5.4 引入。lua_newstate 建出的状态机默认增量模式，但独立解释器 lua 启动时会自动切到分代——命令行跑脚本时分代才是实际生效的模式，Lua 5.4/5.5）基于「多数对象早死」假设：频繁小回收扫新对象，少见大回收扫全堆。5.5 把分代模式下原本停顿式的大回收改为增量式，分摊到多步，延迟更平滑。可用 collectgarbage 切换与调参。

字符类

一律用 % 转义，不是反斜杠。这也意味着模式串里几乎不需要写 \，普通双引号字符串就够用。

量词、锚点与两个特殊项

量词只能跟在单个字符或字符类后面：(ab)* 不合法。需要重复一组东西时只能换思路——这是 Lua 模式最主要的表达力缺口。

捕获

四个函数

gsub 的 repl 可以是三种东西：字符串（里面 %1 引用捕获、%0 是整个匹配）、表（拿捕获当键去查）、函数（拿捕获当参数调用）。后两者返回 nil 或 false 时保留原文不替换——这个性质让「按需替换」很好写。