模块:TypeScript#

稳定性: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 

类型剥离#

默认情况下,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 文件中同时支持 CommonJSES 模块 语法。Node.js 不会将一种模块系统转换为另一种;如果您希望代码作为 ES 模块运行,则必须使用 importexport 语法;如果您希望代码作为 CommonJS 运行,则必须使用 requiremodule.exports

  • .ts 文件的模块系统将以.js 文件相同的方式来确定。要使用 importexport 语法,请在最近的父级 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.jsonallowImportingTsExtensions 选项将允许 TypeScript 编译器 tsc 对包含 .ts 扩展名的 import 说明符的文件进行类型检查。

TypeScript 功能#

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

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

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

不包含运行时代码的 namespacesmodule 是支持的。以下示例将正常工作:

// 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、--checkinspect 中不支持 TypeScript 语法。

源映射(Source maps)#

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

依赖项中的类型剥离#

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

路径别名#

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