在TypeScript的类型系统里，对象字面量并不是永远按照普通的结构类型规则来检查的。编译器会给直接书写出来的对象字面量打上一个临时标记，叫做Freshness，也就是新鲜度。这个标记让对象字面量在直接赋值或传参的瞬间受到更严格的约束，尤其是不能出现目标类型中没有声明的属性。一旦这个字面量被存进变量，或者经过了函数返回等中转，新鲜度就会消失，后续的类型兼容只按结构子类型来判断。
新鲜度的底层机制与触发条件
从实现角度看，Freshness是TypeScript编译器在语法分析阶段为对象字面量表达式附加的一种内部状态。当源码中出现花括号包裹的对象字面量，并且它直接出现在变量初始化、函数调用实参、返回语句等特定语法位置时，编译器会把该表达式标记为fresh。此时进行的类型检查除了验证所有必要属性存在且类型匹配，还会额外遍历字面量中的每一个属性名，确认它们都在目标类型的已知属性集合中。如果发现目标类型未声明的属性，就会抛出所谓 excess property 错误。
这种检查仅作用于“新鲜”的字面量。如果先把对象字面量赋值给一个宽泛类型或相同结构的变量，然后再用这个变量去赋值给更精确的类型，编译器看到的就是一个变量引用而非字面量，新鲜度标记早已在第一次赋值后丢弃。因此同样的对象内容，直接传参会报错，绕一圈存变量却能通过。下面的代码展示了最直接的对比：
interface User {
name: string;
age: number;
}
// 直接传字面量，触发新鲜度检查，报错：'email'不在User中
const u1: User = { name: 'Tom', age: 18, email: 'a@ipipp.com' };
// 先存到变量，新鲜度消失
const temp = { name: 'Tom', age: 18, email: 'a@ipipp.com' };
const u2: User = temp; // 不报错，仅检查结构兼容
需要强调的是，新鲜度不影响运行时的行为，它纯粹是编译期的静态约束。它的设计初衷是捕捉拼写错误，比如把age写成aeg时，普通结构类型可能因为目标类型允许额外属性而放行，但新鲜度检查会立刻指出多余属性。这也解释了为什么使用类型断言或索引签名可以绕过报错：断言相当于告诉编译器“我知道我在做什么”，而索引签名则把多余属性纳入已知范围。
新鲜度与结构化类型的冲突和协作
TypeScript整体采用结构化类型系统，即只要来源对象具备目标类型所需的全部属性且类型相符，就认为赋值合法，不要求属性完全一一对应。新鲜度检查可以看作是对结构化原则在字面量场景下的一种局部修正。它并没有破坏结构化类型，而是在字面量直接出现的地方临时加强约束，从而避免开发者因为手误写出多余字段却毫无感知。
当对象字面量离开“新鲜”状态后，协作关系就回到纯结构化判断。例如一个函数返回了带有额外属性的对象，调用方把返回值赋给精确类型变量不会报错，因为返回值已经是普通对象类型，不再携带新鲜度。这种机制让API内部可以灵活返回丰富数据，而外部使用者仍能按需要的形状去接收。下面的例子说明函数返回场景：
function createUser() {
return { name: 'Lucy', age: 20, email: 'b@ipipp.com' };
}
// 返回值是变量引用，无新鲜度
const user: { name: string; age: number } = createUser();
在团队协作中，理解这一点能减少不必要的类型争吵。如果希望某个配置对象必须严格匹配，不要有多余字段，就应要求调用方直接传字面量或使用精确类型加只读修饰；如果希望允许扩展，则应在类型中声明索引签名，如[key: string]: unknown，这样新鲜度检查也不会把额外属性视为错误。两者并非互斥，而是可以通过类型设计来引导。
实际开发中的避坑策略与写法建议
最常见的问题是在写单元测试或构造请求参数时，直接把带有调试字段的对象字面量传给只接受干净类型的函数，结果编译失败。此时不要盲目使用类型断言as，而应先确认是否真的需要该字段。若字段是临时的，拆出来单独处理；若字段应属于类型的一部分，就回去修改接口定义，补上属性或索引签名，从根源解决。
另一个实用建议是利用Freshness来倒逼接口收敛。在定义配置对象类型时，如果不希望外部乱传属性，就不要加宽松的索引签名，并保持函数参数直接接收字面量。这样任何调用处多写字段都会立即被编译器拦截，相当于把契约写进了类型层。反之，在开发SDK或通用工具时，适度添加索引签名或泛型约束，可以避免使用者每次都要断言，提升体验。
// 严格契约：不允许多余属性
interface StrictConfig {
url: string;
timeout: number;
}
function request(cfg: StrictConfig) {
// ...
}
// 调用处多写字段立刻报错，发挥新鲜度作用
// request({ url: 'http://127.0.0.1', timeout: 1000, retry: 3 });
// 宽松契约：允许扩展
interface LooseConfig {
url: string;
timeout: number;
[extra: string]: unknown;
}
function requestLoose(cfg: LooseConfig) {
// ...
}
requestLoose({ url: 'http://127.0.0.1', timeout: 1000, retry: 3 }); // 正常
最后要注意，Freshness只针对对象字面量，不包括数组字面量或类实例。数组的元素类型检查仍按普通规则，而类实例由于经过构造函数，本身就不是新鲜字面量。明确边界后，就能在代码中预测哪些位置会触发严格检查，哪些不会，从而写出既安全又顺手的TypeScript代码。
TypeScript对象字面量Freshness修改时间：2026-08-13 10:48:38