Node.js 项目关于使用 ts-node 的建议（附ERR_UNKNOWN_FILE_EXTENSION异常解决办法）

以下是针对初学者的 ​​Node.js 项目中使用 ts-node 的详细解答​​，涵盖可行性、优缺点、最佳实践及常见问题的解决方案：

---

一、ts-node 是什么？

ts-node 是一个 ​​TypeScript 运行时工具​ ​，由 TypeStrong 团队开发。它的核心功能是​​直接解析并执行 TypeScript 文件​ ​（.ts/.tsx），无需手动将其编译为 JavaScript（.js）。这极大简化了开发流程，尤其适合需要频繁调试或快速验证代码的场景。

---

二、直接使用 ts-node 运行 TS 文件的可行性

​​结论​​：完全可行，但需满足以下条件：

1. 环境要求

• ​Node.js 版本​ ：建议使用 ​Node.js 14.17+​ （ts-node 依赖 ES Module 特性，旧版本可能不兼容）。
• ​TypeScript 版本​ ：ts-node 需与项目中的 typescript 包版本匹配（建议 typescript >= 4.0）。
• ​依赖安装​ ：需全局或项目内安装 ts-node。

2. 安装方式

# 全局安装（推荐，方便全局使用）
npm install -g ts-node

# 或项目内安装（仅当前项目可用）
npm install ts-node --save-dev

3. 基础使用示例

假设项目中有 src/index.ts 文件：

// src/index.ts
const message: string = "Hello, ts-node!";
console.log(message);

直接运行：

ts-node src/index.ts  # 输出：Hello, ts-node!

​​无需手动编译​ ​，ts-node 会自动调用 typescript 编译器解析并执行代码。

---

三、ts-node 的优缺点分析

优点（开发阶段推荐）

1. ​高效调试​：无需等待编译，修改代码后直接运行，适合快速验证逻辑。
2. ​简化流程​ ：跳过 tsc 编译步骤，减少开发时的重复操作。
3. ​支持原生 ES Module​ ：无需配置 tsconfig.json 的 module 为 CommonJS，直接使用 import/export 语法。

缺点（生产环境不推荐）

1. ​性能开销​：每次运行都需解析和编译 TS 代码，比预编译的 JS 文件慢（尤其对大项目）。
2. ​无法利用 Node.js 缓存​：Node.js 对 JS 文件有缓存机制，但 TS 文件每次运行都会重新编译，无法复用缓存。
3. ​类型检查限制​ ：ts-node 默认仅执行类型检查（--check 模式），但不会生成 d.ts 声明文件（需额外配置）。

---

四、最佳实践建议

1. ​​开发阶段：优先使用 ts-node​​

• ​​适用场景​​：本地开发、调试、快速验证功能。

• ​​推荐命令​​：

  # 直接运行 TS 文件（自动编译+执行）
  ts-node src/index.ts
  
  # 监听文件变化，自动重新运行（适合实时调试）
  ts-node --watch src/index.ts

2. ​​生产环境：预编译为 JS​​

• ​​原因​​：生产环境需要稳定的性能和可预测的行为，预编译的 JS 文件更可靠。

• ​​推荐流程​​：

  1. 使用 tsc 编译 TS 代码到 dist 目录：

     tsc  # 根据 tsconfig.json 配置编译（输出到 dist）

  2. 运行编译后的 JS 文件：

     node dist/index.js

3. ​​结合 npm scripts 优化工作流​​

在 package.json 中配置脚本，统一管理开发和生产命令：

{
  "scripts": {
    "dev": "ts-node src/index.ts",          // 开发模式（直接运行 TS）
    "dev:watch": "ts-node --watch src/index.ts", // 监听模式
    "build": "tsc",                         // 编译 TS 到 JS（生产环境）
    "start": "node dist/index.js"           // 生产环境启动
  }
}

4. ​​配置 tsconfig.json 提升体验​​

为了让 ts-node 更高效工作，需正确配置 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",         // 目标 JS 版本（Node.js 14+ 支持）
    "module": "ESNext",         // 模块系统（ES Module，与 ts-node 兼容）
    "outDir": "./dist",          // 编译输出目录（生产环境用）
    "rootDir": "./src",          // 源码根目录
    "strict": true,              // 严格类型检查（推荐）
    "esModuleInterop": true,     // 兼容 ES/CJS 模块
    "skipLibCheck": true,        // 跳过第三方库检查（提升速度）
    "resolveJsonModule": true    // 支持导入 JSON 文件（可选）
  },
  "include": ["src/**/*"],       // 需要编译的文件
  "exclude": ["node_modules"]    // 排除依赖目录
}

五、总结：一句话建议

• ​开发阶段​ ：直接使用 ts-node 运行 TS 文件（npm run dev），提升调试效率。
• ​生产环境​ ：预编译为 JS（npm run build），运行 dist 目录中的 JS 文件（npm run start）。
• ​配置关键​ ：正确配置 tsconfig.json（module: "ESNext"、outDir: "./dist"），并结合 npm scripts 统一管理流程。

通过以上实践，你可以在 Node.js 项目中高效使用 ts-node，同时确保生产环境的稳定性和性能！ 🚀

六、附ERR_UNKNOWN_FILE_EXTENSION异常及解决办法

采用v22.18.0版本node安装的ts-node直接运行ts文件时，会出现如下错误:

PS D:\ts-node> ts-node.\src\readFile.ts
TypeError: Unknown file extension ".ts" for D:\ts-node\src\readFile.ts
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:219:9)
    at defaultGetFormat (node:internal/modules/esm/get_format:245:36)
    at defaultLoad (node:internal/modules/esm/load:120:22)
    at async ModuleLoader.loadAndTranslate (node:internal/modules/esm/loader:483:32)
    at async ModuleJob._link (node:internal/modules/esm/module_job:115:19) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

参考 typescript.tv/hands-on/fi...

​​问题背景​​

• ​错误原因​ ：在 Node.js v20+ 中使用 TypeScript 和 ts-node 时，由于 Node.js 对 ECMAScript 模块（ESM）的支持增强，默认加载机制不再直接支持 .ts 文件，导致 ERR_UNKNOWN_FILE_EXTENSION 错误。
• ​核心冲突​ ：TypeScript 编译器（tsc）默认输出 JavaScript，而 ts-node 在旧版本中可直接执行 TypeScript，但新版 Node.js 的 ESM 规范改变了这一机制。

---

​​解决方案​​

1. ​​临时修复方案（推荐）​​

# 使用 tsc 进行类型检查，再通过 ts-node 转译执行
PS D:\ts-node> tsc --noEmit && node --no-warnings=ExperimentalWarning --loader ts-node/esm/transpile-only .\src\readFile.ts

• ​​关键点​​：

  • tsc --noEmit：仅进行类型检查，不生成 JavaScript 文件。
  • --loader ts-node/esm/transpile-only：通过实验性加载器转译 TypeScript，避免栈跟踪丢失问题。
  • --no-warnings=ExperimentalWarning：抑制 Node.js 的实验性功能警告。

2. ​​相关调试命令​​

```
node --loader ts-node/esm .\src\readFile.ts
node --no-warnings=ExperimentalWarning --loader ts-node/esm .\src\readFile.ts
```