Angular tsconfig.json中lib属性配置示例

lib 属性

在 SAP Spartacus 等 Angular 应用中，tsconfig.json 文件里有一个常被忽视却至关重要的配置项——lib 属性。它的值通常设置为 es2020 和 dom，如下方截图所示：

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

当然，实际项目中的需求千差万别，lib 的值完全可以按需调整。这就引出了几个典型的应用场景。

常见应用场景

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

lib 支持的值

• ES5：包含 ES3 和 ES5 所有功能的 ES5 核心定义。
• ES2015（即 ES6）：额外包含 Array.prototype.find、Promise、Proxy、Symbol、Map、Set、Reflect 等。
• ES6：ES2015 的别名。
• ES2016（ES7 别名）：包含 Array.prototype.includes 等。
• ES2017：包含 Object.entries、Object.values、Atomics、SharedArrayBuffer、Date.prototype.toLocaleDateString、类型化数组等。
• ES2018：包含 async iterables、Promise.prototype.finally、Intl.PluralRules、正则表达式命名捕获组等。
• ES2019：包含 Array.prototype.flat、Array.prototype.flatMap、Object.fromEntries、String.prototype.trimStart、String.prototype.trimEnd 等。
• ES2020：包含 String.prototype.matchAll 等。
• ES2021：包含 Promise.any、String.prototype.replaceAll 等。
• ESNext：随 JavaScript 规范发展而动态变化的最新 API。
• DOM：窗口、文档等浏览器 DOM 定义。
• WebWorker：Web Worker 上下文中的 API。
• ScriptHost：Windows 脚本宿主系统专用。

举个例子，只要在 lib 里加上了 dom 定义，Angular 应用里就能放心使用 DOM 相关的 API，无需额外声明类型：

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