Angular应用中tsconfig.json配置文件的lib属性完整示例解析教程

TypeScript tsconfig.json 中的 lib 属性详解

在 SAP Spartacus 这类 Angular 应用开发中，tsconfig.json 文件里有一个容易被忽略但至关重要的配置项——lib 属性。它通常被设置为 es2020 和 dom，正如下方截图所示：

这个属性的核心作用，是告诉 TypeScript 编译器哪些内置的 JavaScript API 类型定义是可用的。TypeScript 自身带有一套默认的类型定义，涵盖了 Math 这样的 JS 内置对象，以及 document 等浏览器环境对象。此外，TypeScript 还会根据你所指定的目标（target）版本，自动提供对应的新 JS 特性 API —— 例如当目标设为 ES6 或更高版本时，Map 的类型定义会自动包含进来。

当然，实际项目的需求千差万别，lib 属性的值完全可以按需调整。下面列出几个典型的应用场景。

lib 属性的常见应用场景

• 如果你的程序并不运行在浏览器环境中，例如 Node.js 环境，那么就不需要 dom 类型定义。
• 运行时平台通过 polyfills 提供了部分 JavaScript API 对象，但尚未支持某个 ECMAScript 版本的完整语法。
• 你只对某个高级 ECMAScript 版本的部分功能做了 polyfill 或本机实现。

lib 属性支持的完整值列表

• ES5：包含 ES3 和 ES5 所有功能的 ES5 核心定义。
• ES2015（即 ES6）：额外包含 array.find、Promise、Proxy、Symbol、Map、Set、Reflect 等 API。
• ES6：与 ES2015 是同一别名。
• ES2016（ES7 别名）：包含 array.include 等特性。
• ES2017：包含 Object.entries、Object.values、Atomics、SharedArrayBuffer、date.formatToParts、类型化数组等。
• ES2018：包含 async iterables、promise.finally、Intl.PluralRules、regexp.groups 等。
• ES2019：包含 array.flat、array.flatMap、Object.fromEntries、string.trimStart、string.trimEnd 等。
• ES2020：包含 string.matchAll 等。
• ES2021：包含 promise.any、string.replaceAll 等。
• ESNext：随着 JavaScript 规范发展而动态更新的最新 API 集合。
• DOM：包含窗口、文档等浏览器 DOM 定义。
• WebWorker：WebWorker 上下文中的 API 定义。
• ScriptHost：Windows 脚本宿主系统专用。

举例来说，只要在 lib 中加入了 dom 定义，Angular 应用里就能直接使用 DOM 相关 API，无需额外声明类型：

理解了这个配置的原理后，你就能根据项目的实际运行环境灵活调整 lib 的值，避免类型定义过多或不足带来的编译问题。说到底，TypeScript 的灵活性正体现在这些细节参数的组合上，而 lib 正是其中不起眼却至关重要的一环。