放弃 tsc 使用 tsx 构建Node 环境下 TypeScript + ESM 开发环境搭建指南

放弃 tsc+nodemon 使用 tsx 构建Node 环境下 TypeScript + ESM 开发环境搭建指南

目标

在 node 环境下构建 typescript + esmodule模块 开发环境,这样可以使用 typescript 提供的类型安全和类型提示便利性。

我们要实现下面的效果

  1. 文件目录
  2. src/index.ts 注意是 esmodule 规范
  3. 运行效果

TSX 模块介绍

TSX 模块 TSX 是一个专为现代 Node.js 设计的 TypeScript 运行时,它替代了传统的 ts-node--loader 方案,特别适合在 ESM 环境下使用。

  1. 原生 ESM 支持 - 完全支持 Node.js 的 ES Modules 规范 - 无需额外的 --loader--experimental 标志 - 自动处理 .ts.tsx 文件导入
  2. 高性能 - 使用 Rust 编写的快速转译器 (基于 SWC) - 比传统 ts-node 快 5-20 倍 - 智能缓存机制减少重复编译
  3. 零配置 - 自动检测项目中的 tsconfig.json - 内置支持 TypeScript 路径映射 - 自动处理 CommonJS 和 ESM 互操作
  4. 替代nodemon - tsx watch 会监视文件变化并自动重新加载

为什么选择 ESM?

ES Modules 是 JavaScript 的官方模块标准,相比传统的 CommonJS (CJS) 具有以下优势:

  • 静态分析能力,便于 tree-shaking
  • 浏览器原生支持
  • 更好的异步加载特性
  • 更清晰的模块语法

环境准备

确保你已安装:

  • Node.js 16+ (推荐 20+ 或最新 LTS 版本)
  • pnpm(推荐) 或者 npm 或 yarn
  • 代码编辑器 (VS Code 推荐)

项目初始化

bash 复制代码
mkdir ts-esm-project
cd ts-esm-project
pnpm init

安装必要依赖

sql 复制代码
pnpm install typescript @types/node --save-dev
pnpm install tsx --save-dev

配置 TypeScript

创建 tsconfig.json 文件:

json 复制代码
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

关键配置说明:

  • "module": "NodeNext" - 使用 Node.js 的模块系统
  • "moduleResolution": "NodeNext" - 使用 Node.js 的模块解析算法
  • "esModuleInterop": true - 允许与 CommonJS 模块互操作

配置 package.json

修改 package.json

json 复制代码
{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node ./dist/index.js",
    "dev": "tsx watch src/index.ts",
    "test": "NODE_OPTIONS='--import tsx' vitest"
  },
  "devDependencies": {
    "tsx": "^4.7.0",
    "typescript": "^5.3.0"
  }
}

项目结构示例

css 复制代码
ts-esm-project/
├── src/
│   ├── index.ts
│   ├── utils/
│   │   └── helper.ts
├── tsconfig.json
├── package.json

示例代码

src/index.ts:

javascript 复制代码
import { readFile } from 'node:fs/promises';
import { helper } from '@/utils/helper';// 文件后缀js ts 或者不加都可以

const main = async () => {
  const content = await readFile('./package.json', { encoding: 'utf-8' });
  console.log('Package content:', content);
  helper();
};

main().catch(console.error);

src/utils/helper.ts:

javascript 复制代码
export function helper() {
  console.log('Helper function called');
}

import { helper } from '@/utils/helper';// 文件后缀 js ts 或者不加都可以

开发工作流

  1. 开发模式​:

    arduino 复制代码
    npm run dev

    tsx watch 会监视文件变化并自动重新加载

  2. 生产构建​:

    arduino 复制代码
    npm run build

    生成的文件会输出到 dist/ 目录

  3. 运行生产代码​:

    sql 复制代码
    npm start

常见问题解决(可能遇到)

1. 文件扩展名问题

ESM 要求导入时必须指定完整扩展名。解决方案:

arduino 复制代码
// 正确
import './utils/index.js' 
// 正确
import './utils/index' 
// 正确
import './utils/index.ts' 
// 错误
import './utils'

2. __dirname 替代方案

ESM 中没有 __dirname,替代方案:

javascript 复制代码
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = dirname(fileURLToPath(import.meta.url));

3. 第三方模块兼容性

如果遇到 ESM/CJS 混合问题,可以尝试:

  1. 检查该模块是否有 ESM 版本

  2. 使用动态导入:

    dart 复制代码
    const { default: pkg } = await import('some-package');

测试环境配置

推荐使用 Vitest:

css 复制代码
npm install vitest --save-dev

vite.config.ts:

php 复制代码
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['**/*.test.ts'],
    globals: true
  }
});

部署注意事项

  1. 生产环境应该运行编译后的 .js 文件

  2. 确保 package.json 中包含:

    json 复制代码
    {
      "type": "module",
      "engines": {
        "node": ">=18.0.0"
      }
    }

总结

666666666666666666666666

相关推荐
gnip6 分钟前
微前端框架选型
前端·javascript
芒果12516 分钟前
【转载文章】ECharts-GL 实现世界级、国家级、省市级 3D 地图
前端
一只小风华~26 分钟前
JavaScript:数组常用操作方法的总结表格
前端·javascript·数据结构·vue.js·算法
前端老鹰31 分钟前
JavaScript Array.prototype.some ():数组判断的 “快捷侦探”
前端·javascript
张元清32 分钟前
揭秘JS事件循环:一道字节跳动面试题带你深入理解async/await、Promise与RAF
前端·react.js·面试
KenXu35 分钟前
F2C-Chrome插件-Figma免费的DevMode来了!
前端
北海几经夏41 分钟前
React组件中的this指向问题
前端·react.js
passer9811 小时前
列表项切换时同步到可视区域
前端
FogLetter1 小时前
移动端适配的终极奥义:从lib-flexible到postcss-pxtorem的全方位指南
前端·postcss
易元1 小时前
设计模式-访问者模式
前端·后端·设计模式