【Lua实战】string.gsub 的替换陷阱与转义规则

实战应用：用在哪里

gsub 是 Lua 字符串处理的主力：聊天内容的敏感词替换、物品名的高亮包装、日志的格式清洗都靠它。但模式字符与替换字符的两套转义规则是重灾区——一个没转义的百分号让替换结果面目全非。

模式字符的转义

---用户输入进模式前必须转义
local function escape(s)
    return (s:gsub("([%%%.%+%-%*%?%[%]%^%$%(%)])", "%%%1"))
end

local item = "裁决之杖[极]"          -- 玩家自定义名字带魔法字符
local plain = "装备[" .. escape(item) .. "]已上架"
print(plain:match("装备%[(.-)%]已上架"))

模式的魔法字符共 12 个：百分号、点、加减号、星号、问号、方括号、尖号、美元符与圆括号，escape 函数逐个加百分号转义。玩家可自定义的名字与聊天内容进模式匹配前不转义，一个括号就能让匹配报错或越界，这是聊天过滤与搜索功能的必修课。

替换串的规则

---替换串里 %1 引用捕获，字面百分号要翻倍
local s = "击杀祖玛教主 获得 裁决之杖"
print((s:gsub("(%S+)%s+(%S+)", "[%1|%2]"))

---函数替换：按内容动态决定替换值
local out = s:gsub("祖玛教主", function(w)
    return "<BOSS>" .. w .. "</BOSS>"
end)
print(out)

替换串的第一参数里 %1 到 %9 引用捕获组，想输出字面的百分号要写成两个。替换第三参数传函数时，每个匹配调用一次，返回值即为替换值，返回 nil 或 false 则保留原文——动态替换的场景（按物品品质决定高亮颜色）函数形式最干净。性能的账：百万次 gsub 约 0.9 秒，已知无模式的纯文本替换用 plain 参数的 string.find 配合 sub 手工替换，能快四成。

验证与监控

替换函数的单测覆盖魔法字符全集与边界：空串、纯魔法字符、超长串；聊天过滤的误替换率监控，误替换的样本回填测试用例。

踩坑记录

玩家名字带百分号直接进 gsub 的模式参数，匹配直接抛异常，escape 进所有动态模式的入口后绝迹。替换串曾经想输出字面的 %1，写了一个百分号被当成捕获引用，翻倍写法才对。函数替换里曾经返回了含 % 的字符串没再转义——函数返回值不经过替换串解析，这里是安全的，但维护者不知道这条规则，注释写明省得反复踩。

上线要点

escape 函数进公共库，代码评审检查所有动态模式的入口。聊天与搜索的正则需求先问一句是否真的需要模式匹配，plain 能解决的不上模式。gsub 的第三个参数（替换次数）默认全替换，限量替换的场景显式传参，语义显式化减少误读。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。