TypeScript 开发利器：ts-node 与 tsx 实战指南

在日常开发中，我们经常需要编写和运行 TypeScript 脚本来测试功能或自动化任务。本文将详细介绍如何使用 ts-node 和 tsx 直接运行 TypeScript 文件，以及解决过程中可能遇到的常见问题。

为什么需要直接运行 TypeScript？

TypeScript 需要编译成 JavaScript 才能被 Node.js 执行，这个过程通常需要两个步骤：

1. 使用 tsc 将 TypeScript 编译为 JavaScript
2. 使用 node 执行编译后的 JavaScript 文件

这个流程在开发阶段非常繁琐，尤其是需要频繁修改和测试代码时。幸运的是，我们有更便捷的工具可以一步到位。

方案一：使用 ts-node

安装依赖

yarn add -D ts-node typescript @types/node
# 或者
npm install -D ts-node typescript @types/node

⚠️ 注意：建议将这些依赖安装在项目本地而非全局，以避免版本冲突问题。

配置步骤

1. 在 tsconfig.json 中添加必要配置：

{
  "compilerOptions": {
    "module": "ESNext",  // 或 "ES2015"
    "moduleResolution": "node", // 必须添加
    "esModuleInterop": true,
    "target": "ES2020",
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

2. 在 package.json 中设置模块类型：

{
  "type": "module"
}

3. 在导入语句中必须包含文件扩展名：

// ❌ 错误写法
import data from './data'

// ✅ 正确写法
import data from './data.js'

运行命令

# 方式一
ts-node --esm ./src/script.ts

# 方式二
node --loader ts-node/esm ./src/script.ts

你也可以在 package.json 中添加快捷命令：

{
  "scripts": {
    "dev": "ts-node --esm ./src/script.ts"
  }
}

方案二：使用 tsx（推荐）

tsx 是一个基于 esbuild 的现代化替代方案，提供了更快的执行速度和更简单的配置。

安装

yarn add -D tsx
# 或者
npm install -D tsx

使用方式

tsx ./src/script.ts

添加到 package.json 中：

{
  "scripts": {
    "dev": "tsx ./src/script.ts",
    "watch": "tsx watch ./src/script.ts"
  }
}

tsx 的优势

• 更快的启动速度：基于 esbuild，比 ts-node 快 10-20 倍
• 零配置：无需复杂的 tsconfig 设置
• 内置支持：自动支持 TypeScript、JSX 和 ESM
• 开发友好：内置了 node-fetch 等常用模块
• 监视模式：支持 watch 模式自动重启

常见问题及解决方案

1. 无法使用 import 语句

SyntaxError: Cannot use import statement outside a module

解决方案：在 package.json 中添加 "type": "module"

2. 找不到模块

Error [ERR_MODULE_NOT_FOUND]: Cannot find module

解决方案：

• 添加文件扩展名（.js 或 .ts）
• 检查路径是否正确
• 确保依赖已正确安装

3. TypeScript 文件扩展名报错

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"

解决方案：

• 使用正确的命令格式：node --loader ts-node/esm
• 或直接使用 tsx

4. fetch 未定义

ReferenceError: fetch is not defined

解决方案：

• 使用 ts-node 时需要安装 node-fetch：

  yarn add node-fetch
  import fetch from 'node-fetch';
  

• 使用 tsx 时已内置，无需额外安装

性能对比

写在最后

1. 选择建议：对于新项目，强烈推荐使用 tsx，它提供了更好的开发体验和性能
2. 问题排查：遇到问题时，建议优先查看 GitHub Issues，通常能找到最准确的解决方案
3. 依赖管理：请确保项目依赖安装在本地，避免使用全局安装导致的版本冲突问题
4. 调试技巧：结合 VS Code 的调试功能，可以更高效地开发和测试 TypeScript 脚本