企业官网建设流程全解析

1. 先搞清楚问题从哪来：泛型方法与扩展方法在 xLua 里的真实处境

做到第 38 篇，这个话题基本是每个接 xLua 的项目都会撞上的一堵墙。前三十几篇里我们把 LuaEnv 的创建、模块加载、CSharpCallLua 委托绑定、热更补丁流程都过了一遍，轮到"定义 C# 泛型方法与扩展方法"的时候，很多人会卡在一个很尴尬的位置：C# 那边代码写得好好的，编译通过，单元测试也过，切到 Lua 侧一调，要么方法压根是 nil，要么报一个看不懂的转换异常。这篇就把这块彻底拆开讲清楚。

先把标题里三个关键词摆明：Unity提供宿主环境，XLua提供 Lua 与 C# 的桥接层，泛型方法与扩展方法是我们想在 C# 侧定义、并希望 Lua 侧能用上的两类成员。解决的问题很具体——让热更脚本能复用 C# 里已经写好的通用逻辑，而不用在 Lua 里重写一遍。适合谁看？已经在项目里接好 xLua、能正常跑通CS.UnityEngine.GameObject这种基础调用、但一涉及<T>和this参数就开始发懵的中级开发者；也适合做技术选型和代码规范的同学，因为这两类成员能不能用、怎么用，直接决定了你们的 Lua 业务层要写多少重复代码。

我先把结论摆在前面，省得你看到一半才发现方向不对。扩展方法在 Lua 侧基本可以放心用，本质是静态方法，只要把所在的静态类配进生成列表，调用方式清晰稳定。泛型方法在 Lua 侧不能直接调，不是配置漏了，是桥接层的生成机制决定的，必须靠 C# 侧包一层非泛型外壳把类型固定下来。这两条差异决定了整个章节的组织方式，也是我在项目里定代码规范时的核心依据。

1.1 一次热更需求引出的三个卡点

我印象很深的一次，是给一个战斗模块做热更。策划临时要改伤害计算里的取整规则，逻辑不复杂，问题是我们原来的实现散落在十几个 C# 类里，Lua 侧要复现一遍成本极高。当时的想法很朴素：把这些通用逻辑抽成几个工具类，Lua 直接调。结果动手之后连着撞了三堵墙。

第一堵墙是集合操作。C# 侧有个TryGetValue<TKey, TValue>风格的泛型读取方法，参数是两个泛型，Lua 侧写CS.Game.Util.Config.Get(cfg, "hp")直接报 attempt to call a nil value。第二堵墙是组件获取。Lua 里想拿一个Transform，照着文档写go:GetComponent(CS.UnityEngine.Transform)，报参数类型不匹配，因为那个重载要的是Type而不是类型本身。第三堵墙是字符串和表的便捷方法。我们 C# 里有一堆xxx.IsNullOrEmpty()这类扩展方法，Lua 侧写str:IsNullOrEmpty()完全没反应，方法不存在。

这三个卡点看起来风马牛不相及，其实根源是同一个：Lua 侧能看见的成员，是 xLua 的代码生成器"挑"出来注册进去的，不是 C# 里有什么就能看见什么。生成器不认识的东西，你在 Lua 里就是找不到。想通这一层，后面所有的疑惑都能顺着解开。

注意：不同 xLua 版本的生成行为存在差异，尤其是较新的版本对泛型和扩展方法的支持在逐步加强。本文的结论基于主流稳定版本的实际表现，动手前建议先用一个最小 demo 验证你当前版本的行为，别直接照搬到大项目里。

1.2 桥接代码决定了 Lua 能看见什么

xLua 的核心机制是"生成代码"。你在编辑器里点一次 Generate Code，它会在指定目录下产出大量 C# 文件，每个文件对应一个被标记的类型，里面是__Register注册函数和一串成员包装方法。Lua 侧访问CS.命名空间.类型名.成员名的时候，走的是这套注册好的映射表。

这就解释了很多"玄学"现象。为什么UnityEngine下的类基本都能用？因为 xLua 内置了一份基础配置，把常用引擎类型都纳入了生成范围。为什么你自己写的类偶尔能用偶尔不能用？因为没打标记的类型走的是反射回退路径，性能差、行为也不完全一致，而且某些成员根本不在回退路径的支持范围内。为什么泛型方法调不到？因为生成器在遍历成员的时候，遇到开放泛型（也就是<T>还没确定的形态），没法枚举出所有可能的类型实例，只能跳过。

我这里说的"跳过"，你完全可以自己验证一遍，方式很直接：生成代码之后，去输出目录里找到对应类型的 Wrap 文件，用文本搜索你的方法名。非泛型方法一定在，泛型方法一定不在。这个动作比看任何文档都快，也是我带新人时让他们做的第一件事——遇到"方法找不到"的问题，先去生成代码里搜名字，一搜就知道是配置问题还是机制问题。

1.3 两类成员的本质差异对照

把泛型方法和扩展方法放在一起对比，能快速建立正确的心理预期。很多人的误区是把它们当成同一类"高级语法糖"，实际上在桥接层里的处境完全不同。

这张表我在团队内部分享时反复用过，它解决的其实是预期管理问题。你只要接受"泛型要在 C# 侧落地、扩展方法是普通静态方法"这个前提，后面写代码就不会拧巴。反过来说，如果你抱着"Lua 是动态语言，泛型应该更灵活"的想法去做，那一定会在这上面浪费掉一两天。

2. 泛型方法：Lua 侧调不到不是 bug，是设计使然

这一节把泛型彻底讲透。我不打算只给一个"包一层"的结论，那样你下次遇到变体还是会懵。我们要搞清楚的是：为什么不行、什么情况下"看起来行了"、以及包一层的时候有哪些隐含成本。

2.1 从生成代码目录里找答案

先做一个可复现的观察实验，这一步比读十页文档管用。在你的工程里建一个测试类，同时放一个普通方法和一个泛型方法：

namespace Game.Test { public class GenericDemo { public int NormalAdd(int a, int b) => a + b; public T Echo<T>(T value) => value; } }

把GenericDemo通过特性或配置类加入 LuaCallCSharp 列表，执行 Generate Code，然后去生成目录打开Game_Test_GenericDemoWrap.cs。你会看到NormalAdd有对应的注册和调用代码，而Echo完全不见踪影——搜索 "Echo" 一个结果都没有。

原因不复杂。生成器的工作方式是遍历类型的公开成员，为每一个成员写一段从 Lua 栈读参数、调用、把返回值压栈的胶水代码。对普通方法，参数类型是确定的，读栈逻辑能写死。对Echo<T>，T在生成的那一刻是未知的，生成器没法写出"从 Lua 栈读一个 T 类型值"的代码，因为 Lua 里的值到 C# 具体类型的转换规则完全依赖目标类型。于是它只能跳过。

这里有个容易踩的坑：有些人会误以为只要T是引用类型就能调通。实际上能不能调通跟T是值类型还是引用类型没关系，跟"生成器有没有为某个具体实例化生成代码"有关系。在某些版本里，如果你在配置里显式写了一个封闭泛型（比如把某个用到List<MyClass>的方法暴露出来），生成的代码可能会带上具体实例化的版本，这时候 Lua 侧就"看起来能用"了。但这种行为依赖版本和配置细节，我不建议把它作为项目的基础设施依赖，属于"能用但不敢依赖"的那一类。

2.2 引用类型参数和值类型参数的实际差异

虽然"能不能调"跟类型类别无关，但"调通之后的开销"跟类型类别关系极大，这一点在性能敏感的项目里必须提前想清楚。

假设你写了一个包装方法，把泛型参数统一收成object：

public object Wrap(object arg) { return DoSomething(arg); }

如果 Lua 侧传进来的是数字（Lua 的 number 到了 C# 侧通常按 double 或者 int 处理），进入object参数就必然产生装箱。装箱意味着在托管堆上分配一个小对象，意味着 GC 压力。战斗场景里如果每帧调用几百次，每秒就是几万次小分配，这在我们一个中大型项目里直接把 GC 尖峰拉高了一截，最后是靠改成强类型重载才压下去的。

引用类型就没这个问题，传的是引用，不装箱。所以我的经验是：给 Lua 用的包装层，尽量为常用的值类型参数写强类型重载，比如GetInt(string key)、GetFloat(string key)、GetBool(string key)，而不是一个GetValue(string key, Type t)走天下。多写几个方法的成本，远低于后期排查 GC 尖峰的成本。

2.3 三种包装策略与我为什么选第三种

知道要包一层之后，怎么包就有讲究了。我试过三种，各有适用场景。

第一种是"反射兜底"：Lua 侧传方法名字符串，C# 侧用MethodInfo.MakeGenericMethod动态调。写起来最省事，一个入口搞定所有泛型方法。问题也很明显：反射调用本身开销大，参数类型全丢失，出错只能靠运行时异常发现，而且MakeGenericMethod在 IL2CPP 环境下有裁剪风险，很容易在真机上炸。我只在纯编辑器工具里用过这种方式，运行时从来不用。

第二种是"泛型参数类型枚举"：暴露一个入口，第二个参数传类型标记字符串，内部 switch 分发到具体实例化。比反射安全，但每个方法都要写一遍 switch，代码量爆炸，而且字符串拼错就是运行时错误。

第三种是"窄接口 + 显式类型枚举"，这是我最终在项目里定下来的方案。具体做法是：不暴露泛型方法本身，而是针对每类实际需求，写一个语义明确、参数强类型、返回值强类型的普通方法。比如不缺一个通用的Get<T>(key)，而是写GetInt(key)、GetString(key)、GetIntArray(key)。这些方法内部去调泛型实现，对 Lua 而言它们就是普通方法，生成器正常处理，Lua 正常调用，没有装箱，没有反射，出问题在编译期就能发现。

这个方案的代价是方法数量变多。但换个角度想，你其实是在为 Lua 侧设计一套面向业务的窄接口，本来就不该把 C# 的通用泛型直接铺给脚本层。脚本层用得最多的一定是那么十来个固定类型，把高频的写死，低频的走通用兜底，是最务实的做法。我在一个加载了上百个 Lua 模块的项目里用这套方案跑了两年多，泛型相关的线上问题基本为零。

提示：包一层的代码放在独立的静态类里，不要和业务类混在一起。原因是生成代码的粒度是类型，独立的"桥接类"你能清楚地知道哪些东西是给 Lua 用的，后续要收敛、要下线、要做安全审计都方便。

3. 扩展方法：静态方法穿了个马甲

扩展方法这块，多数人的困惑集中在"为什么我写了this参数，Lua 里还是找不到"。答案往往简单得让人无语：扩展方法在编译后就是普通静态方法，它属于那个静态类，不属于被扩展的类型。你的配置只加了被扩展的类型，当然找不到。

3.1 编译后的真实形态

先用一个例子把编译后的形态说明白。C# 里写：

namespace Game.Ext { public static class TransformExt { public static void SetPosX(this UnityEngine.Transform t, float x) { var p = t.localPosition; p.x = x; t.localPosition = p; } } }

这段代码编译之后，TransformExt里有一个公开静态方法SetPosX(Transform t, float x)。C# 编译器只是在语法层面允许你写t.SetPosX(1f)，编译出来还是TransformExt.SetPosX(t, 1f)。运行时的元数据里没有任何"这是 Transform 的成员"的信息，只有一个ExtensionAttribute作为标记。

明白这一点，Lua 侧的调用方式就顺理成章了：把它当静态方法调。也就是CS.Game.Ext.TransformExt.SetPosX(transform, 1.5)，第一个参数传目标对象。这种写法在任何版本上都成立，因为它走的是最基础的静态方法访问路径。

那transform:SetPosX(1.5)这种冒号写法行不行？我的实测结论是：部分版本、部分类型可行，具体取决于生成器有没有把扩展方法挂到目标类型的注册表上。我确实见过能跑通的版本，也见过升级之后失效的版本。所以项目里我统一规定用静态调用，冒号写法在代码评审时会被打回去。这不是因为冒号写法不好看，而是因为它把一个版本相关的行为当成了基础设施，风险不对等。

注意：冒号写法如果没生效，报错信息通常是 attempt to call a nil value，看起来像是"方法不存在"，很容易误导你去查生成配置。实际原因可能是扩展方法没被挂载。这种情况直接换成静态调用验证一下，能快速定位。

3.2 配置与生成验证的完整流程

配置这块我按实际动手顺序列一遍，都是踩过坑之后固定下来的动作。

第一步，确定扩展方法所在静态类的完整命名空间和类名。写错一个字母，生成器就找不到。我习惯在建类的时候就把它放进一个专门的LuaExposed目录，类名统一加Ext后缀，一眼能认出是给 Lua 用的。

第二步，加标记。两种方式二选一：在类上直接打[XLua.LuaCallCSharp]，或者在集中配置类里用LuaCallCSharp列表添加typeof(TransformExt)。我个人偏好集中配置，理由是给 Lua 用的东西集中在一个文件里，能一眼看完整个对外暴露的接口面，做安全审查和新同学上手都方便。散落的特性则容易在重构时被漏掉。

第三步，执行 Generate Code。这一步有个很常见的坑：生成之后如果 LuaEnv 已经初始化过，必须重启播放模式或者重建 LuaEnv，否则用的还是旧的注册表。我见过不止一个人改完配置直接跑，然后说"没用"，其实只是没重启。

第四步，验证。在 Lua 里打印CS.Game.Ext.TransformExt，如果输出是一个表（而不是 nil），说明类注册成功；再打印CS.Game.Ext.TransformExt.SetPosX，输出应该是 function 类型。这两步打印能覆盖九成配置问题，剩下的才是参数类型和重载匹配的事。

第五步，如果需要冒号写法，单独验证一次。写个小脚本print(transform.SetPosX)看是不是 nil。是 nil 就老老实实用静态调用，别在这上面纠缠。

3.3 给 LuaTable 写扩展方法：一个能直接抄的例子

光讲概念不够，给一个我们项目里真实用过的场景。Lua 侧传过来一个 table 当配置，C# 侧要读里面的字段做校验。XLua.LuaTable提供了Get<T>(string key)这样的泛型方法，在 Lua 里直接调是调不通的，正好用扩展方法包一层。

using XLua; namespace Game.Ext { public static class LuaTableExt { public static int GetInt(this LuaTable table, string key, int defaultValue = 0) { if (table == null) return defaultValue; return table.Get<string, int>(key, defaultValue); } public static string GetString(this LuaTable table, string key, string defaultValue = "") { if (table == null) return defaultValue; return table.Get<string, string>(key, defaultValue); } public static bool GetBool(this LuaTable table, string key, bool defaultValue = false) { if (table == null) return defaultValue; return table.Get<string, bool>(key, defaultValue); } } }

注意这里的细节。LuaTable.Get有多个重载，Get<TKey, TValue>(TKey key, TValue defaultValue)这个重载的行为是"键不存在时返回默认值、类型不匹配时抛异常或返回默认值，取决于版本配置"。我特意显式传默认值，是为了让行为在不同版本间保持一致，避免出现"有时返回 nil 有时抛错"的玄学。

另一个细节是空判断。Lua 传过来的 table 有可能已经被释放（比如 LuaEnv 被 Dispose 了），这时候访问会抛异常。加一层 null 判断成本极低，能省掉很多莫名其妙的崩溃。

配置上，把typeof(LuaTableExt)加入 LuaCallCSharp 列表。这里有个容易忽略的点：被扩展的类型LuaTable本身也需要能被 Lua 侧识别。xLua 内置支持 LuaTable，一般不需要额外配置，但如果你用到的是自定义类型，记得两个都加上。

Lua 侧调用长这样：

local Ext = CS.Game.Ext.LuaTableExt local cfg = { hp = 100, name = "soldier", alive = true } print(Ext.GetInt(cfg, "hp", 0)) -- 100 print(Ext.GetString(cfg, "name", "")) -- soldier print(Ext.GetBool(cfg, "alive", false)) -- true print(Ext.GetInt(cfg, "mp", 50)) -- 50，键不存在走默认值

这套封装在我们项目里用了很久，好处是 Lua 侧完全不用关心Get<T>的类型参数语法，用起来跟调用普通函数一样。而且因为是强类型重载，没有装箱，GC 表现很干净。这就是我前面说的"窄接口"思路的落地形态——不是把 C# 的通用能力原样端给 Lua，而是为 Lua 的常见用法裁剪出一组专用入口。

4. 手把手跑通一次：从 C# 定义到 Lua 调用再到性能观察

前面讲原理，这一节走一遍完整流程。我按一个真实的小需求来设计：战斗模块需要在 Lua 侧调整角色的位置偏移、读取配置表字段、并做一些通用集合操作。这个场景能同时覆盖扩展方法和泛型包装两条线。

4.1 C# 侧按"接口层与实现层"分离来写

我习惯把给 Lua 用的东西分成两层。实现层是真正干活的，可以随便用泛型、用 LINQ、用各种高级语法；接口层是暴露给 Lua 的，只允许普通方法、强类型参数、简单返回类型。这样做的原因是：实现层将来可能被 C# 业务代码复用，写法不必迁就 Lua 的限制；接口层则严格控制对外暴露的面积，改动影响可控。

实现层示例：

namespace Game.Core { using System.Collections.Generic; public static class CollectionCore { public static TValue GetOrAdd<TKey, TValue>( Dictionary<TKey, TValue> dict, TKey key, System.Func<TValue> factory) { if (dict.TryGetValue(key, out var v)) return v; v = factory(); dict[key] = v; return v; } } }

接口层就是这个泛型方法的非泛型外壳。假设我们实际只需要"从缓存字典里取一个单位对象，没有就创建"，那就写一个语义明确的方法：

namespace Game.Bridge { using System.Collections.Generic; using UnityEngine; using XLua; [LuaCallCSharp] public static class UnitCacheBridge { private static readonly Dictionary<int, GameObject> _cache = new Dictionary<int, GameObject>(); public static GameObject GetOrCreateUnit(int unitId, string prefabPath) { return CollectionCore.GetOrAdd(_cache, unitId, () => Resources.Load<GameObject>(prefabPath)); } public static void ClearCache() { _cache.Clear(); } } }

这段代码里，泛型方法GetOrAdd只出现在 C# 侧，Lua 侧看到的是GetOrCreateUnit(int, string)，参数类型明确，返回值明确，没有装箱，生成器能正常处理。资源加载这种重操作放在工厂委托里，只有缓存未命中才执行，这是常见的缓存策略，省掉了每次调用都判断一遍的重复逻辑。

位置调整这类需求走扩展方法：

namespace Game.Bridge { using UnityEngine; using XLua; [LuaCallCSharp] public static class TransformBridge { public static void AddLocalPosX(this Transform t, float delta) { if (t == null) return; var p = t.localPosition; p.x += delta; t.localPosition = p; } public static void SetLocalScale(this Transform t, float scale) { if (t == null) return; t.localScale = new Vector3(scale, scale, scale); } } }

这里我把AddLocalPosX参数设成增量而不是绝对值，是为了配合 Lua 侧"每帧累加"的用法。如果暴露成绝对值，Lua 侧每次都要先读当前值再算，多一次跨语言调用。这种"把计算下推到 C# 侧"的思路，在跨语言边界上非常值钱——一次跨语言调用的开销，通常是同逻辑纯 C# 计算的几十倍，能合并就合并。

4.2 配置清单与生成代码的正确姿势

配置我统一放在一个文件里，方便审查：

namespace Game.Bridge { using System.Collections.Generic; using UnityEngine; using XLua; public static class LuaBridgeConfig { [LuaCallCSharp] public static List<System.Type> LuaCallCSharpList = new List<System.Type> { typeof(UnitCacheBridge), typeof(TransformBridge), typeof(Game.Bridge.LuaTableExt), }; } }

这里用了List<Type>形式的配置，这是 xLua 支持的语法之一，等价于逐个打特性。它的好处是集中、可搜索、便于做差异对比——代码评审时看这个文件就能知道这次改动往 Lua 侧多暴露了什么。

生成的正确姿势我总结成四步：

1. 保存所有 C# 改动，确认编译无错误。编译有错的话生成器会用旧的程序集，你以为改了其实没改。
2. 菜单里执行 Generate Code，等它跑完，观察控制台有没有 warning。warning 里经常藏着"某个类型找不到"之类的线索。
3. 执行 Clear Generated Code 再重新生成一次。这步不是必须，但我在遇到"改了配置没生效"时一定会做，属于排除法里的低成本操作。
4. 退出播放模式，重新进入。LuaEnv 初始化时才会读取注册表，不重启就可能用到旧的。

生成完成后，去目录里确认三个文件存在：UnitCacheBridgeWrap.cs、TransformBridgeWrap.cs、LuaTableExtWrap.cs。打开其中一个，搜索你的方法名，能找到就说明注册成功。这个验证动作我坚持了两年，帮我省掉无数次"为什么调不到"的困惑。

4.3 Lua 侧调用脚本与验证点

写一段能直接跑的验证脚本，把两条线都覆盖到：

local UnitBridge = CS.Game.Bridge.UnitCacheBridge local TransBridge = CS.Game.Bridge.TransformBridge local TableExt = CS.Game.Bridge.LuaTableExt -- 验证类是否注册成功 print("UnitBridge =", UnitBridge) print("GetOrCreateUnit =", UnitBridge.GetOrCreateUnit) -- 泛型包装层的调用 local unit = UnitBridge.GetOrCreateUnit(1001, "Prefabs/Unit/1001") print("unit =", unit) -- 扩展方法的静态调用 local trans = unit.transform TransBridge.AddLocalPosX(trans, 0.5) TransBridge.SetLocalScale(trans, 1.2) -- 扩展方法 + LuaTable 组合用法 local cfg = { speed = 3, name = "runner" } print("speed =", TableExt.GetInt(cfg, "speed", 0)) print("name =", TableExt.GetString(cfg, "name", "")) -- 冒号写法单独验证，观察当前版本行为 print("colon style =", trans.AddLocalPosX)

最后一行是我特意留的探针。这个打印能告诉你当前版本到底支不支持冒号写法：输出 function 就支持，输出 nil 就不支持。别把它当结论，当成一次对环境的体检。项目换引擎版本、升级 xLua 版本时重新跑一次这段，能提前发现问题。

几个验证要点值得单独说。第一，print一个类名如果输出 table 说明注册成功，输出 nil 说明配置没生效，这时候别去查方法，先查类。第二，print方法名输出 function 还是 nil，能区分"类注册了但方法没生成"和"类都没注册"两种完全不同的情况。第三，调用之后看返回值类型对不对，有时候方法调通了但返回值被转成了意料之外的类型，问题出在类型映射上而不是方法暴露上。

4.4 用 Profiler 和 GC 数据说话

接口层写完之后一定要测一次性能，不能凭感觉判断"应该没问题"。我的做法是在 Lua 脚本里跑一个循环，调一万次，用 Unity Profiler 观察 CPU 和 GC Alloc 两栏。

测试脚本大致长这样：

local TransBridge = CS.Game.Bridge.TransformBridge local trans = CS.UnityEngine.GameObject("test").transform local t0 = CS.UnityEngine.Time.realtimeSinceStartup for i = 1, 10000 do TransBridge.AddLocalPosX(trans, 0.001) end local t1 = CS.UnityEngine.Time.realtimeSinceStartup print("10000 calls cost:", t1 - t0)

一万次调用的耗时量级通常在几十毫秒，具体取决于机器和版本。重点不是绝对值，而是看 GC Alloc 那一栏有没有持续增长。如果每次调用都分配，一万次下来就是几 MB，这在真机上会直接体现在帧率波动上。

我踩过一次坑：早期的包装层用了params object[]收可变参数，看起来通用性很强，结果每次调用都 new 一个数组，一万次调用分配了几百 KB，在低端机上直接引发了一次 GC。改成固定参数重载之后，分配降到零。这个教训让我在给 Lua 设计接口时立了一条规矩：热路径上的接口，禁止出现params、禁止object参数、禁止在内部 new 引用类型。

还有一个观察点：调用频率高不高、能不能合批。如果 Lua 侧一个循环里连续调十次同类方法，考虑在 C# 侧加一个批量版本。跨语言边界的成本是按次算的，把十次合成一次，收益非常直接。

5. 踩坑记录：报错、假成功与性能陷阱

这一节全是实战里攒下来的。我把报错信息、成因、解决方式整理成表，遇到问题直接查表比翻文档快。

5.1 常见报错逐条拆解

attempt to call a nil value (field 'XXX')是最常见的一个。原因有三个可能：类没进生成列表、方法名拼错、方法是泛型方法没被生成。排查顺序是先打印类名确认注册，再打印方法名，最后去生成代码里搜方法名。三步走下来基本能定位。

InvalidCastException: Cannot cast from source type to destination type通常出在参数类型不匹配上。Lua 的 number 到了 C# 侧默认可能被当成 double，如果你的方法签名是int而调用时传了一个看起来像整数的浮点，某些版本会直接抛异常。解决方式是签名用double然后在内部转换，或者在 Lua 侧显式用math.floor转一下。我倾向于前者，把兼容性做在 C# 侧。

ArgumentException: Get generic type definition failed出现在试图通过反射拿开放泛型的时候，多见于自己写工具类去批量导出泛型方法。这类代码建议直接放弃，收益不匹配风险。

还有一个不太好定位的：调用明明成功，但结果不对。这种情况常见于重载匹配。C# 有多个同名重载时，Lua 侧传参的类型决定了匹配哪一个，如果类型模糊（比如整数既能匹配 int 又能匹配 float），可能匹配到你没预期的那一个。解决办法很简单——给 Lua 用的接口避免重载，一个语义一个方法名，GetInt和GetFloat分开写，别用同一个名字。

5.2 问题速查表

这张表建议直接贴在项目 wiki 里。我带过的几个项目都有类似的表，新人遇到问题先自己查一遍，团队沟通成本能降一大截。

5.3 几条只有踩过才知道的经验

第一条，给 Lua 的接口一定要"少而稳"。我见过有项目把整个 C# 业务层用特性一标，全部暴露给 Lua，图省事。结果是任何一次 C# 重构都可能悄悄破坏热更脚本，而且没人说得清 Lua 到底用了哪些接口。后来我们改成白名单机制，一个新接口要暴露，必须走评审，必须在配置文件里显式登记。成本是每次多写一行配置，收益是接口面始终可控。

第二条，扩展示方法的第一个参数一定要判空。Lua 侧传 nil 过来是家常便饭，忘了判空就是 NullReferenceException，而且堆栈里看不出是哪个脚本传的，排查起来非常痛苦。所有给 Lua 用的静态方法，我在开头都会写一行 null 检查，这已经成了肌肉记忆。

第三条，不要在给 Lua 的接口里做重活。跨语言调用本身有成本，如果接口内部还做字符串拼接、LINQ 查询、资源加载，一次调用的耗时可能到毫秒级，Lua 侧循环几十次就会造成明显卡顿。重活要么拆成异步、要么在 C# 侧预先算好。我们有个项目在初始化时一次性把所有配置算好放进字典，Lua 侧只做查表，这个改动的收益比任何代码优化都大。

第四条，版本升级一定要跑回归脚本。泛型和扩展方法的行为在不同版本间有差异，升级之后那套验证脚本必须重跑一遍。我习惯把那几个打印语句固化成一个check_bridge.lua，每次升级先跑它，看到全是 function 再继续。

第五条，文档比记忆可靠。哪些方法暴露给了 Lua、哪些是泛型包装、哪些是扩展方法，全都记在配置文件和生成目录里，别靠脑子记。半年后回来看代码的人可能是你自己，那时候你一定不记得当初为什么这么写。

最后分享一个我们现在的做法：所有给 Lua 的桥接类，命名空间统一带Bridge后缀，文件统一放在Assets/Scripts/Bridge下，每个文件顶部写一段注释说明这个类暴露给哪个 Lua 模块使用、什么时候可以下线。这套约定执行下来，桥接层的代码量能控制在几千行以内，审查和重构都在可控范围内。泛型和扩展方法本身不难，难的是让整个团队对"什么该暴露、怎么暴露"有一致的判断，这才是这类基础设施真正需要解决的问题。