译：Node.js 项目中的 TypeScript

在 Node.js 中搭建 TypeScript 项目一开始可能看起来比较麻烦，但只要按照正确的步骤操作，很快就能让一切顺利运行起来。无论你是在编写一个小脚本还是一个完整的应用程序，本指南都会带你逐步完成整个过程。

我们将从零开始，配置 TypeScript，并使用最佳实践搭建一个简单的开发环境。让我们开始吧！

首先，你需要为项目创建一个专用文件夹。打开终端并运行以下命令：

// Command Line
mkdir my-project
cd my-project
npm init -y

让我们来拆解一下每个命令的作用：

• mkdir my-project：创建一个新的项目目录。
• cd my-project：进入新创建的目录。
• npm init -y：使用默认值初始化一个新的 package.json 文件。

这个 package.json 文件对 Node.js 项目至关重要，因为它管理着项目的依赖和脚本。

Node.js 中的 TypeScript

现在，让我们将 TypeScript 作为开发依赖项进行安装，并创建一个配置文件：

// Command Line
npm install --save-dev typescript
touch tsconfig.json

让我们来拆解一下每个命令的作用：

• npm install --save-dev typescript：为你的项目本地安装 TypeScript。
• touch tsconfig.json：创建一个 TypeScript 配置文件。

接下来，在你的 tsconfig.json 文件中添加以下配置：

{
  "compilerOptions": {
    /* 现代 JavaScript 与浏览器兼容性： */
    "target": "ESNext", // 使用最新的 ECMAScript 特性以支持现代 JavaScript

    /* 模块系统设置： */
    "module": "NodeNext", // 配置 Node.js 使用 ESM 模块系统
    "rootDir": "src", // 指定代码的源目录
    "outDir": "dist", // 指定编译文件的输出目录
    "sourceMap": true, // 启用源映射以方便调试

    /* 模块解析策略： */
    "moduleResolution": "NodeNext", // 使用 Node 的 ESM 策略解析模块
    "moduleDetection": "force", // 强制 TypeScript 将文件视为模块

    /* 互操作性和文件命名一致性： */
    "esModuleInterop": true, // 确保 CommonJS 和 ESM 模块之间的兼容性
    "forceConsistentCasingInFileNames": true, // 防止跨平台的大小写敏感问题

    /* 严格类型检查： */
    "strict": true, // 启用严格类型检查以减少运行时错误
    "noUncheckedIndexedAccess": true, // 强制对数组/对象访问进行类型安全检查
    "noImplicitOverride": true, // 强制对重写基类方法的方法显式使用 `override`
    "noImplicitAny": true, // 除非显式定义，否则禁止使用 `any` 类型
    "skipLibCheck": true, // 跳过声明文件的类型检查以加快编译速度
    "resolveJsonModule": true, // 允许将 JSON 文件作为模块导入
    "declaration": true, // 生成 `.d.ts` 文件用于类型定义
    "allowSyntheticDefaultImports": true, // 允许对 CommonJS 模块进行默认导入
    "verbatimModuleSyntax": true, // 保持 `import`/`export` 语法不变，不进行转换

    // 为前端包含现代 ECMAScript (ES2022) 和 DOM API
    "lib": ["ES2022", "DOM"] // 为前端开发包含 ES2022 特性和 DOM API
    // 对于没有 DOM API 的后端代码，请取消注释以下内容
    /* "lib": ["ES2022"] */
  },
  "include": ["src"], // 将 `src` 目录包含在项目中
  "exclude": ["node_modules", "dist"] // 从项目中排除 `node_modules` 和 `dist` 目录
}

可选择添加以下行以在 TypeScript 项目中支持 JavaScript：

// tsconfig.json
{
  "compilerOptions": {
    ...
    "allowJs": true,
    "checkJs": true
  }
}

如果我们要完全采用 ESM（ECMAScript 模块），请在 package.json 中添加以下内容：

{
  "type": "module"
}

源文件夹和入口文件

创建一个 src 文件夹，并在其中创建一个 index.ts 文件：

// Command Line
mkdir src
touch src/index.ts

现在，在 src/index.ts 中添加一个简单的 TypeScript 脚本：

// src/index.ts
console.log("Hello world!");

这将作为我们的起点，以确保一切正常运行。

在 Node.js 中运行和编译 TypeScript 文件

若要直接运行 TypeScript 文件而无需先进行编译，可以安装 tsx，它是一款流行的 TypeScript 运行器。另一种选择是使用 ts-node：

// Command Line
npm install tsx --save-dev

你也可以在 Node.js 中原生使用 类型剥离，但 tsx 完全支持 TypeScript 的各项特性。现在，请更新 package.json 中的脚本以使用 tsx：

// package.json
"scripts": {
  "dev": "tsx src/index.ts",
  "build": "tsc",
  "start": "node dist/index.js"
}

让我们来拆解一下每个脚本的作用：

• "dev": "tsx src/index.ts":
  • 使用 tsx 以开发模式运行项目。此脚本在开发过程中使用。
• "build": "tsc":
  • 使用 TypeScript 编译器 (tsc) 将 TypeScript 文件编译为 JavaScript。编译后的文件存储在 dist 文件夹中。
• "start": "node dist/index.js":
  • 运行编译后的 JavaScript 文件。此脚本在生产环境中使用。

若要实现自动重载，请更新 dev 脚本：

// package.json
"scripts": {
  "dev": "tsx --watch src/index.ts",
  "build": "tsc",
  "start": "node dist/index.js"
}

--watch 标志会让 tsx 在文件发生更改时自动重新编译并重新加载文件。

Node.js 中的环境变量

许多应用程序需要敏感的 API 密钥和环境变量。最佳实践是将它们存储在 .env 文件中，而不是硬编码在代码里。在项目目录中创建一个 .env 文件，并添加以下内容：

# .env
OPENAI_API_KEY="sk-proj-123abc"

然后，修改 src/index.ts 文件以读取环境变量：

// src/index.ts
console.log(process.env.OPENAI_API_KEY);

为确保 TypeScript 能够识别环境变量，请安装 Node.js 类型定义：

// Command Line
npm install @types/node --save-dev

如果你使用的是 Node.js 20.6.0 或更高版本，可以直接使用 --env-file 标志来加载环境变量：

// package.json
"scripts": {
  "dev": "tsx --watch --env-file=.env src/index.ts",
  "build": "tsc",
  "start": "node --env-file=.env dist/index.js"
}

若要采用更完善的方法，可以考虑使用 dotenv 包：

// Command Line
npm install dotenv

修改 src/index.ts 文件，使用 dotenv 加载 .env 文件：

// src/index.ts
import "dotenv/config";

console.log(process.env.OPENAI_API_KEY);

相应地更新 package.json 中的脚本：

// package.json
"scripts": {
  "dev": "tsx --watch src/index.ts",
  "build": "tsc",
  "start": "node dist/index.js"
}

现在，你的项目可以安全地读取环境变量了。

---

就是这样！你已经成功使用 Node.js 搭建了一个 TypeScript 项目。下面快速回顾一下我们所做的操作：

• 使用 npm init 创建一个新的 Node.js 项目
• 安装并配置 TypeScript
• 设置一个包含 TypeScript 入口文件的源目录
• 安装 tsx 以便高效运行 TypeScript 文件
• 使用 .env 文件配置环境变量
• 使用 dotenv 更好地管理环境变量

现在你已经准备好开始构建由 TypeScript 驱动的 Node.js 应用程序了！