'# Can't run my Node.js Typescript project TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension
一、背景与问题
在Node.js项目中使用TypeScript时，开发者常遇到TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension错误。这个错误的核心原因是Node.js默认不支持TypeScript文件的扩展名.ts。TypeScript需要经过编译器处理，将.ts文件转换为JavaScript代码才能被Node.js执行。
该错误的典型场景包括：
- 直接运行
node index.ts - 在
package.json中未配置TypeScript相关依赖 - 未正确配置TypeScript编译器选项
- 项目结构中包含大量
.ts文件但未指定编译规则
理解这一错误的底层原理是解决问题的关键。Node.js的模块系统需要明确的文件扩展名来确定如何加载模块，而TypeScript文件的特殊性需要额外的配置。
二、基本原理
TypeScript是JavaScript的超集，其核心在于编译时的类型检查和转换。当使用TypeScript时，必须经过以下流程：
- TypeScript源文件（
.ts） → 编译器（tsc） → JavaScript目标文件（.js） - Node.js执行JavaScript目标文件
Node.js的模块系统通过require()/import机制加载文件，其核心是根据文件扩展名确定加载方式。对于.ts文件，Node.js默认没有内置的处理逻辑。
TypeScript编译器通过以下配置控制转换行为：
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"strict": true
}
}其中关键配置项：
target：指定ECMAScript版本module：指定模块系统类型（CommonJS/ES Modules）outDir：指定输出目录strict：启用严格类型检查
三、环境准备
创建一个基础项目结构：
my-ts-project/
├── src/
│ └── index.ts
├── tsconfig.json
├── package.json
└── README.md安装必要依赖：
npm init -y
npm install --save-dev typescript四、核心实现
1. 基础配置（使用tsc编译）
创建tsconfig.json：
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true
},
"include": ["src"]
}执行编译：
npx tsc运行程序：
node dist/index.js关键点：
outDir指定输出目录include指定需要编译的源文件目录esModuleInterop启用ES模块兼容性
2. 使用ts-node直接运行（开发环境）
安装依赖：
npm install --save-dev ts-node配置package.json：
{
"scripts": {
"start": "ts-node src/index.ts"
}
}运行程序：
npm start关键点：
ts-node会自动编译并运行TypeScript代码- 适合开发环境使用，但不推荐生产环境
3. 使用TypeScript编译器API（高级用法）
创建compile.ts：
import * as ts from 'typescript';
const sourceFile = ts.createSourceFile(
'index.ts',
'console.log("Hello, TypeScript!")',
ts.ScriptTarget.Latest,
false
);
const printer = ts.createPrinter({
target: ts.ScriptTarget.Latest,
module: ts.ModuleKind.CommonJS
});
printer.printNode(ts.EmitHint.Unspecified, sourceFile, null);运行程序：
node compile.ts关键点：
- 使用TypeScript编译器API手动控制编译过程
- 适用于需要深度定制编译流程的场景
五、完整案例
创建完整项目结构：
my-ts-project/
├── src/
│ └── index.ts
├── tsconfig.json
├── package.json
└── README.mdsrc/index.ts内容：
import { hello } from './utils';
console.log(hello());src/utils.ts内容：
export function hello() {
return 'Hello, TypeScript!';
}tsconfig.json配置：
{
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true,
"moduleResolution": "node"
},
"include": ["src"]
}package.json配置：
{
"name": "my-ts-project",
"version": "1.0.0",
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
},
"devDependencies": {
"typescript": "^5.0.0"
}
}运行流程：
npm install
npm build
npm start六、源码解析
以tsconfig.json配置为例，重点解析关键字段：
{
"compilerOptions": {
"target": "ES2020", // 指定目标JavaScript版本
"module": "CommonJS", // 指定模块系统类型
"outDir": "./dist", // 指定输出目录
"strict": true, // 启用严格类型检查
"esModuleInterop": true, // 启用ES模块兼容性
"moduleResolution": "node" // 指定模块解析策略
},
"include": ["src"] // 指定需要编译的源文件目录
}模块解析策略：
node：使用Node.js的模块解析算法（默认）classic：使用CommonJS的解析方式
七、进阶使用
1. 配置文件优化
大型项目可使用多个tsconfig.json文件：
{
"compilerOptions": {
"composite": true,
"outDir": "./dist"
},
"references": [
"./tsconfig.api.json",
"./tsconfig.utils.json"
]
}2. 模块解析策略
对于混合使用CommonJS和ES Modules的项目：
{
"compilerOptions": {
"moduleResolution": "node",
"module": "ESNext"
}
}3. 代码生成优化
使用transpileOnly提高性能：
{
"compilerOptions": {
"transpileOnly": true
}
}八、性能与工程实践
1. 性能优化
- 使用
transpileOnly避免类型检查 - 启用
watch模式进行实时编译 - 使用缓存机制避免重复编译
2. 安全风险
- 避免在生产环境使用
ts-node - 使用
tsconfig.json的exclude排除敏感文件 - 启用
strict选项预防类型错误
3. 异常处理
配置tsconfig.json的moduleResolution：
{
"compilerOptions": {
"moduleResolution": "node"
}
}九、常见问题与踩坑
1. 错误示例
错误配置：
{
"compilerOptions": {
"outDir": "./dist",
"module": "ESNext"
}
}问题：未配置moduleResolution导致模块解析失败
2. 错误解决
正确配置：
{
"compilerOptions": {
"outDir": "./dist",
"module": "ESNext",
"moduleResolution": "node"
}
}3. 其他常见问题
- 忘记安装typescript包
tsconfig.json配置错误- 模块路径不正确
十、最佳实践
- 使用
tsconfig.json统一配置 - 启用
strict选项确保类型安全 - 使用
transpileOnly提高开发性能 - 在生产环境使用
tsc编译后运行 - 合理配置
include和exclude字段
十一、总结
TypeError [ERR_UNKNOWN_FILE_EXTENSION]错误的根本原因是Node.js对TypeScript文件的扩展名不支持。通过合理配置tsconfig.json文件，可以解决该问题。在开发过程中，建议使用ts-node进行快速开发，而在生产环境应使用tsc进行编译后运行。理解TypeScript的编译流程和配置选项，是确保项目稳定运行的关键。通过合理配置和实践，可以充分发挥TypeScript在Node.js项目中的优势，同时避免常见的陷阱和错误。