模块：TypeScript#

历史
版本变更
v24.3.0, v22.18.0

类型剥离不再发出实验性警告。

v23.6.0, v22.18.0

类型剥离功能默认启用。

v22.7.0

增加了 --experimental-transform-types 标志。

稳定性：1.2 - 候选发布

启用#

在 Node.js 中有两种方法可以启用对 TypeScript 的运行时支持。

  1. 要完全支持所有 TypeScript 的语法和功能，包括使用任意版本的 TypeScript，请使用第三方包。

  2. 若需轻量级支持，您可以使用内置的类型剥离功能。

完整的 TypeScript 支持#

要使用 TypeScript 并完全支持其所有功能，包括 tsconfig.json，您可以使用第三方包。以下说明以 tsx 为例，但还有许多其他类似的库可用。

  1. 使用您项目中使用的任何包管理器将该包安装为开发依赖项。例如，使用 npm：

    npm install --save-dev tsx

  2. 然后您可以通过以下方式运行您的 TypeScript 代码：

    npx tsx your-file.ts

    或者，您也可以通过 node 运行：

    node --import=tsx your-file.ts

类型剥离#

添加于：v22.6.0

默认情况下，Node.js 将执行仅包含可擦除 TypeScript 语法的 TypeScript 文件。Node.js 会将 TypeScript 语法替换为空格，并且不执行类型检查。要启用对不可擦除 TypeScript 语法的转换（这需要生成 JavaScript 代码，例如 enum 声明、参数属性），请使用标志 --experimental-transform-types。要禁用此功能，请使用标志 --no-experimental-strip-types。

Node.js 会忽略 tsconfig.json 文件，因此，依赖于 tsconfig.json 中设置的功能（例如路径或将较新的 JavaScript 语法转换为旧标准）被有意地不支持。要获得完整的 TypeScript 支持，请参见完整的 TypeScript 支持。

类型剥离功能被设计为轻量级的。通过有意不支持需要生成 JavaScript 代码的语法，并将内联类型替换为空格，Node.js 可以在不需要源映射（source maps）的情况下运行 TypeScript 代码。

类型剥离与大多数 TypeScript 版本兼容，但我们建议使用 5.8 或更新版本，并采用以下 tsconfig.json 设置：

{
  "compilerOptions": {
     "noEmit": true, // Optional - see note below
     "target": "esnext",
     "module": "nodenext",
     "rewriteRelativeImportExtensions": true,
     "erasableSyntaxOnly": true,
     "verbatimModuleSyntax": true
  }
}

如果您只打算执行 *.ts 文件（例如构建脚本），请使用 noEmit 选项。如果您打算分发 *.js 文件，则不需要此标志。

确定模块系统#

Node.js 在 TypeScript 文件中同时支持 CommonJS 和 ES 模块 语法。Node.js 不会将一种模块系统转换为另一种；如果您希望代码作为 ES 模块运行，则必须使用 import 和 export 语法；如果您希望代码作为 CommonJS 运行，则必须使用 require 和 module.exports。

  • .ts 文件的模块系统将以与 .js 文件相同的方式来确定。要使用 import 和 export 语法，请在最近的父级 package.json 文件中添加 "type": "module"。
  • .mts 文件将始终作为 ES 模块运行，类似于 .mjs 文件。
  • .cts 文件将始终作为 CommonJS 模块运行，类似于 .cjs 文件。
  • 不支持 .tsx 文件。

与 JavaScript 文件一样，在 import 语句和 import() 表达式中，文件扩展名是强制性的：import './file.ts'，而不是 import './file'。出于向后兼容性的原因，文件扩展名在 require() 调用中也是强制性的：require('./file.ts')，而不是 require('./file')，这类似于在 CommonJS 文件中 require 调用强制要求使用 .cjs 扩展名。

tsconfig.json 的 allowImportingTsExtensions 选项将允许 TypeScript 编译器 tsc 对包含 .ts 扩展名的 import 说明符的文件进行类型检查。

TypeScript 功能#

由于 Node.js 仅移除内联类型，任何涉及将 TypeScript 语法*替换*为新的 JavaScript 语法的 TypeScript 功能都会报错，除非传递了 --experimental-transform-types 标志。

需要转换的最突出的功能是：

  • Enum 声明
  • 包含运行时代码的 namespace
  • 包含运行时代码的旧式 module
  • 参数属性
  • 导入别名

不包含运行时代码的 namespaces 和 module 是支持的。以下示例将正常工作：

// This namespace is exporting a type
namespace TypeOnly {
   export type A = string;
}

这将导致 ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX 错误：

// This namespace is exporting a value
namespace A {
   export let x = 1
}

由于装饰器（Decorators）目前是 TC39 Stage 3 提案，并且很快将得到 JavaScript 引擎的支持，因此它们不会被转换，并将导致解析器错误。这是一个临时限制，将来会得到解决。

此外，Node.js 不会读取 tsconfig.json 文件，也不支持依赖于 tsconfig.json 中设置的功能，例如路径或将较新的 JavaScript 语法转换为旧标准。

不使用 type 关键字导入类型#

由于类型剥离的特性，type 关键字对于正确剥离类型导入是必需的。如果没有 type 关键字，Node.js 会将导入视为值导入，这将导致运行时错误。可以使用 tsconfig 选项 verbatimModuleSyntax 来匹配此行为。

以下示例将正常工作：

import type { Type1, Type2 } from './module.ts';
import { fn, type FnParams } from './fn.ts';

这将导致运行时错误：

import { Type1, Type2 } from './module.ts';
import { fn, FnParams } from './fn.ts';

非文件形式的输入#

可以为 --eval 和 STDIN 启用类型剥离。模块系统将由 --input-type 决定，就像对 JavaScript 一样。

在 REPL、--check 和 inspect 中不支持 TypeScript 语法。

源映射（Source maps）#

由于内联类型被替换为空格，因此源映射对于在堆栈跟踪中获得正确的行号是不必要的；Node.js 也不会生成它们。当启用 --experimental-transform-types 时，源映射默认启用。

依赖项中的类型剥离#

为了不鼓励包作者发布用 TypeScript 编写的包，Node.js 拒绝处理 node_modules 路径下文件夹中的 TypeScript 文件。

路径别名#

tsconfig 的 "paths" 不会被转换，因此会产生错误。最接近的可用功能是子路径导入，但其限制是必须以 # 开头。