Node.js项目TypeScript改造指南

前言

如果你有一个 Node.js 项目，并想使用 TypeScript 进行改造，那本文对你或许会有帮助。

TypeScript 越来越火，本文不讲为什么要使用 TypeScript，也不讲基本概念。本文讲的是如何将一个旧的 Node.js 项目使用
TypeScript 进行改造，包括目录结构调整、TypeScript-ESLint 配置、tsconfig 配置、调试、常见错误处理等。

由于篇幅有限，Node.js 项目能集成的技术也是五花八门，未覆盖到的场景还请见谅。

步骤一、调整目录结构

Node.js 程序，由于对新语法的支持比较快(如async/await从v7.6.0开始支持)，大部分场景是不需要用到 babel、webapck
等编译工具的，因此也很少有编译文件的dist目录，而 TypeScript
是需要编译的，所以重点是要独立出一个源码目录和编译目标目录，推荐的目录结构如下，另外，根据不同技术栈还有一堆其他的配置文件如
prettier、travis 等等这里就省略了。

---

    
    |-- assets            # 存放项目的图片、视频等资源文件|-- bin               # CLI命令入口，require('../dist/cli')，注意文件头加上#!/usr/bin/env node|-- dist              # 项目使用ts开发，dist为编译后文件目录，注意package.json中main字段要指向dist目录|-- docs              # 存放项目相关文档|-- scripts           # 对应package.json中scripts字段需要执行的脚本文件|-- src               # 源码目录，注意此目录只放ts文件，其他文件如json、模板等文件放templates目录    |-- sub           # 子目录    |-- cli.ts        # cli入口文件    |-- index.ts      # api入口文件|-- templates         # 存放json、模板等文件|-- tests             # 测试文件目录|-- typings           # 存放ts声明文件，主要用于补充第三方包没有ts声明的情况|-- .eslintignore     # eslint忽略规则配置|-- .eslintrc.js      # eslint规则配置|-- .gitignore        # git忽略规则|-- package.json      #|-- README.md         # 项目说明|-- tsconfig.json     # typescript配置，请勿修改

步骤二、TypeScript安装与配置

目录结构调整后，在你的项目根目录执行：

（1）npm i typescript -D，安装 typescript，保存到 dev 依赖

（2）node ./node_modules/.bin/tsc --init，初始化 TypeScript 项目，生成一个 tsconfig.json
配置文件

备注：如果第1步选择全局安装，那第2步中可以直接使用tsc --init。

执行初始化命令后会生成一份默认配置文件，更详细的配置及说明可以自行查阅官方文档，这里根据前面的项目结构贴出一份基本的推荐配置，部分配置下文会解释。

---

{  "compilerOptions": {    // "incremental": true,                   /* 增量编译 提高编译速度*/    "target": "ES2019",                       /* 编译目标ES版本*/    "module": "commonjs",                     /* 编译目标模块系统*/    // "lib": [],                             /* 编译过程中需要引入的库文件列表*/    "declaration": true,                      /* 编译时创建声明文件 */    "outDir": "dist",                         /* ts编译输出目录 */    "rootDir": "src",                         /* ts编译根目录. */    // "importHelpers": true,                 /* 从tslib导入辅助工具函数(如__importDefault)*/    "strict": true,                           /* 严格模式开关 等价于noImplicitAny、strictNullChecks、strictFunctionTypes、strictBindCallApply等设置true */    "noUnusedLocals": true,                   /* 未使用局部变量报错*/    "noUnusedParameters": true,               /* 未使用参数报错*/    "noImplicitReturns": true,                /* 有代码路径没有返回值时报错*/    "noFallthroughCasesInSwitch": true,       /* 不允许switch的case语句贯穿*/    "moduleResolution": "node",               /* 模块解析策略 */    "typeRoots": [                            /* 要包含的类型声明文件路径列表*/      "./typings",      "./node_modules/@types"      ],    "allowSyntheticDefaultImports": false,    /* 允许从没有设置默认导出的模块中默认导入，仅用于提示，不影响编译结果*/    "esModuleInterop": false                  /* 允许编译生成文件时，在代码中注入工具类(__importDefault、__importStar)对ESM与commonjs混用情况做兼容处理*/  
  },  "include": [                                /* 需要编译的文件 */    "src/**/*.ts",    "typings/**/*.ts"  ],  "exclude": [                                /* 编译需要排除的文件 */    "node_modules/**"  ],}

步骤三、源码文件调整

将所有.js文件改为.ts文件

这一步比较简单，可以根据自身项目情况，借助 gulp 等工具将所有文件后缀改成ts并提取到src目录。

模板文件提取

由于 TypeScript 在编译时只能处理 ts、tsx、js、jsx 这几类文件，因此项目中如果用到了一些模板如 json、html
等文件，这些是不需要编译的，可以提取到 templates 目录。

packaeg.json中添加scripts

前面我们将 typescript 包安装到项目