TypeScript 运行器

实验性功能

TypeScript 运行器处于实验阶段，正在积极开发中。API 和行为可能会在不同版本之间发生变化。

oxc-node 是 Oxc 的 TypeScript 运行器。它无需单独的构建步骤即可运行 TypeScript 和 JSX，同时保留标准的 Node.js 命令行工作流。

该运行器提供：

• 用于运行脚本和启动 REPL 的 oxnode 命令。
• 可与 node --import 一起使用的 Node.js 注册钩子。
• 同步和异步转换 API。
• ESM 和 CommonJS 支持。
• 用于堆栈跟踪的源映射。
• tsconfig.json 集成。

CLI

将 @oxc-node/cli 安装为开发依赖：

npm

$ npm add -D @oxc-node/cli

pnpm

$ pnpm add -D @oxc-node/cli

yarn

$ yarn add -D @oxc-node/cli

bun

$ bun add -D @oxc-node/cli

TIP

在项目本地安装可以让团队中的运行器版本保持一致。如果希望在项目或包脚本之外调用 oxnode，也可以全局安装 @oxc-node/cli。

运行 TypeScript 入口文件：

oxnode ./src/index.ts

参数会直接传递给 Node.js，因此监视模式等 Node.js 功能仍然可用：

oxnode --watch ./src/index.ts

不带脚本运行 oxnode 会启动 Node.js REPL。使用 oxnode --node-help 可显示 Node.js 命令行帮助。

如需可重复执行的项目命令，可在 package.json 中添加脚本：

package.json

{
  "scripts": {
    "dev": "oxnode ./src/index.ts"
  }
}

Node.js 注册钩子

当你希望继续直接使用 node 命令时，请安装 @oxc-node/core：

npm

$ npm add -D @oxc-node/core

pnpm

$ pnpm add -D @oxc-node/core

yarn

$ yarn add -D @oxc-node/core

bun

$ bun add -D @oxc-node/core

在加载入口点之前注册 Oxc：

node --import @oxc-node/core/register ./src/index.ts

由于这使用了 Node.js 的注册钩子，因此可以与其他 Node.js 命令和标志组合使用。例如，使用内置测试运行器运行 TypeScript 测试：

node --import @oxc-node/core/register --test ./test.ts

支持的文件

register hook 会转换以下扩展名：

.js .jsx .ts .tsx .mjs .mts .cjs .cts .es6 .es

模块格式根据文件扩展名、最近的 package.json 和 tsconfig.json 推断。默认情况下不会转换 node_modules 中的文件。设置 OXC_TRANSFORM_ALL=1 后也会转换这些文件。

TypeScript 配置

运行器会从当前工作目录读取 tsconfig.json。设置 OXC_TSCONFIG_PATH 或 TS_NODE_PROJECT 以使用其他文件：

OXC_TSCONFIG_PATH=./config/tsconfig.dev.json oxnode ./src/index.ts

转换器会使用与模块格式、JSX、装饰器、类字段以及重写相对导入扩展名相关的编译器选项。转换过程中会移除 TypeScript 类型；运行器不会对你的程序进行类型检查。

链接

• oxc-node 仓库
• @oxc-node/cli
• @oxc-node/core