roblox-luau-types

Luau 类型系统

何时加载

用于 Luau 注解、类型推断、类型收窄、严格模式、导出和求解器功能。语法：roblox-luau-core；生命周期/调度：roblox-luau-patterns。

快速参考

严格模式： 对维护中的代码使用 --!strict，过渡期间使用 --!nonstrict，仅对遗留代码或生成的代码使用 --!nocheck。指令和项目设置决定模式；切勿假定存在全局默认值。

新求解器开关： keyof、rawkeyof、setmetatable<T, M>、type function 和 read 成员需要使用新的类型求解器。nocheck/nonstrict 项目默认启用；严格模式项目需要设置 Workspace.UseNewLuauTypeSolver = Enabled（Scripting）。此处的错误通常意味着求解器不匹配，而非语法错误。

推断理念： 优先使用类型推断；在边界处（参数、返回值、导出）添加注解。不要给每个局部变量都添加注解。

封闭表与开放表： 未添加注解的局部表，在添加新字段之前会保持开放，直到它被添加注解、从函数返回或其作用域结束；添加注解会封闭表。先构建完整的表，再添加注解；将表传给带类型的函数不会封闭该表。

联合类型： local id: string | number 是联合类型；优先使用带标签的联合类型（type State<T> = {kind:"loading"} | {kind:"ready", value:T}），并根据 kind 进行区分以收窄类型。

类型收窄： typeof、IsA、断言和带标签的判别字段可以细化类型；示例见 full.md。

缺失键： 当查找可能失败时，使用 { [K]: V? }；使用前先收窄类型。

封闭词汇表： 优先使用字面量联合类型；never 检查可以标记缺失的分支。确保 require 可在静态阶段解析。实践指导见 full.md。

泛型： 当输入→输出的类型关系很重要时使用泛型：function first<T>(list: {T}): T?，或 type Result<T> = {success: boolean, value: T?}。切勿用 any 替代。

类型导出： 在模块边界使用 export type Foo = {...}；使用方通过 Types.Foo 使用。

对象类型： typeof(setmetatable({} :: CounterData, Counter)) 能为 self 提供精确类型；新求解器直接支持 setmetatable<T, M>。

类型转换（::）： 用于收窄过于宽泛的类型推断，切勿用于掩盖错误。

信任边界： 注解约束的是编译器，而非运行时数据。Remote、DataStore、HttpService 和属性仍需要检查；在可信边界内，让类型系统承担检查工作。

审查： 不要留下隐藏的 any、过早封闭的表、未经检查的类型转换，或忽略求解器的重写。

完整参考：见 references/full.md