搭建Node.js+TypeScript开发环境要点及注意事项

前端开发中的各种脚手架对TypeScript（下称“TS”）支持已经很完善了。但作为后端的Node.js平台似乎对TS的支持还不太多。使用JS开发，习惯了TS的语法提示带来的安全感和便利性，因此迫切需要在Node.js平台下搭建TS开发环境。这个环境中，TS代码修改后将会自动重新编译和运行，不需要反复重新输入编译和运行命令。主要步骤如下：

一、安装全局依赖

1. 安装nodemon，将会得到一个可全局执行的命令nodemon

npm install -g nodemon

2. 安装TypeScript语言编译器，将会得到一个全局可执行的命令tsc

npm install -g typescript@next

二、搭建项目目录框架

1. 创建一个空文件夹，在其内部再创建src和dist两个子文件夹。src目录主要存放源代码，dist目录主要存放编译后的代码。

2. 执行初始化。用VSCode打开主目录，在终端中运行以下命令，将会得到package.json和tsconfig.json两个配置文件：

npm init -y

tsc -init

三、安装必要的依赖

1. 安装TS语言的类型文件，这是实现语法提示的核心包。

npm i --save-dev @types/node

2. 安装Node.js配置包。为方便配置适用于Node.js环境的tsconfig.json文件，TS官方为不同的Node.js版本准备了配置包。需要根据你的Node.js版本安装，假设现有Node.js版本是20.16.0，则执行以下命令：

npm install --save-dev @tsconfig/node20

其他版本的可以到npmjs.org官方网站搜索“@tsconfig”关键字。

3. 安装其他依赖。很多第三方包并不是内置支持TS语言的，因此在安装包本身的同时还要安装其类型文件。假设需要使用express框架，则执行以下命令，安装其依赖和类型文件：

npm i express --save

npm i --save-dev @types/express

四、修改配置

主要修改tsconfig.json文件。关键步骤是引入刚才安装的官方配置文件，指定源文件目录和编译输出目录，其他配置选项就不需要太多了，具体解释如下：

{
  "extends": "@tsconfig/node20/tsconfig.json",  /* 引用官方配置文件 */
  "compilerOptions": {
    "rootDir": "./src/",                                  /* 指定TS源文件所在目录 */
    "outDir": "./dist/"                                  /* 指定编译结果存放目录 */
  }
}

五、测试开发环境

为了测试自定义模块和标准库的导入使用效果，我编写了一个自定义模块。

1. 在src目录下创建一个utils目录，再在其下面创建一个index.ts文件，输入以下代码：

// 判断一个字符串是否合法的手机号
export const isValidMobile = (mobile: string) => {
    let reg = /^1[3456789]\d{9}$/;
    return reg.test(mobile);
};

2. 在src目录下创建一个index.ts文件，输入以下代码：

import express from 'express'
import { isValidMobile } from './utils'
const app = express()
const port = 3000
console.log(isValidMobile('6139000000000'))
app.get('/', (req, res) => {
    res.send('你好，Node.js!')
})

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`)
})

此时，TS的语法提示已经出现了：

六、运行代码

需要开两个终端，一个终端运行tsc命令，另一个运行nodemon命令。就本项目而言，具体命令如下：

1. 运行tsc命令，加上-w或者--watch参数，让tsc监控源文件的修改，从而动态编译。因为在tsconfig.json文件中已经配置了源文件目录，所以简化了命令：

 tsc -w

可以看到，TS语言编译器已经监视源文件目录，并实现了动态编译： 

以下是更新代码后的错误提示：

2. 运行nodemon命令，让它监控输出目录内的文件变化：

nodemon ./dist/index.js

用浏览器打开http://localhost:3000，将会看到以下结果：

可以发现，express框架在响应头内默认添加了utf8编码设置，中文没有乱码。

 七、补充配置

以上介绍的测试办法需要手动输入两次终端命令，稍显不太方便，这里提供同时运行两个 npm 命令的方法：

1. 安装concurrently依赖

npm install concurrently -D 

2. 修改 package.json 文件，在 scripts 属性下面添加以下三行：  

    "tscWatch": "tsc -w",   // 让 tsc 监听 TS 源文件的变化
    "distWatch": "nodemon ./dist/index.js",  // 让 nodemon 监听编译输出文件的变化
    "dev": "concurrently \"npm run tscWatch\" \"npm run distWatch\""  // 同时启动以上两个命令

3. 运行npm run dev 命令，即可以一次性同时打开 tsc 和 nodemon 两个命令，并让他们处于监听状态：如下图所示：

八、注意事项

 使用TS语言编写Node.js程序，最好使用ES6的模块导出和导入方式。使用CommonJS方式导入的对象、方法和产量可能会没有语法提示，如下图所示：

要使CommonJS导入的模块具有类型推导，可能会需要更多配置。

本示例中，使用export导出，使用import导入，就有了语法提示：

本文代码已上传至仓库，拉取方式：

git clone git@gitee.com:war_horse/framework_for_node.js_using_ts.git