# 代碼檢查
2019 年 1 月,[TypeScirpt 官方決定全面采用 ESLint](https://www.oschina.net/news/103818/future-typescript-eslint) 作為代碼檢查的工具,并創建了一個新項目 [typescript-eslint][],提供了 TypeScript 文件的解析器 [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/parser) 和相關的配置選項 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin) 等。而之前的兩個 lint 解決方案都將棄用:
- [typescript-eslint-parser](https://github.com/eslint/typescript-eslint-parser) 已停止維護
- [TSLint](https://palantir.github.io/tslint/) 將提供遷移工具,并在 typescript-eslint 的功能足夠完整后停止維護 TSLint(Once we consider ESLint feature-complete w.r.t. TSLint, we will deprecate TSLint and help users migrate to ESLint<sup>[1](https://medium.com/palantir/tslint-in-2019-1a144c2317a9)</sup>)
綜上所述,目前以及將來的 TypeScript 的代碼檢查方案就是 [typescript-eslint][]。
## 什么是代碼檢查
代碼檢查主要是用來發現代碼錯誤、統一代碼風格。
在 JavaScript 項目中,我們一般使用 [ESLint][] 來進行代碼檢查,它通過插件化的特性極大的豐富了適用范圍,搭配 [typescript-eslint][] 之后,甚至可以用來檢查 TypeScript 代碼。
## 為什么需要代碼檢查
有人會覺得,JavaScript 非常靈活,所以需要代碼檢查。而 TypeScript 已經能夠在編譯階段檢查出很多問題了,為什么還需要代碼檢查呢?
因為 TypeScript 關注的重心是類型的檢查,而不是代碼風格。當團隊的人員越來越多時,同樣的邏輯不同的人寫出來可能會有很大的區別:
- 縮進應該是四個空格還是兩個空格?
- 是否應該禁用 `var`?
- 接口名是否應該以 `I` 開頭?
- 是否應該強制使用 `===` 而不是 `==`?
這些問題 TypeScript 不會關注,但是卻影響到多人協作開發時的效率、代碼的可理解性以及可維護性。
下面來看一個具體的例子:
```ts
var myName = 'Tom';
console.log(`My name is ${myNane}`);
console.log(`My name is ${myName.toStrng()}`);
```
以上代碼你能看出有什么錯誤嗎?
分別用 tsc 編譯和 eslint 檢查后,報錯信息如下:
```ts
var myName = 'Tom';
// eslint 報錯信息:
// Unexpected var, use let or const instead.eslint(no-var)
console.log(`My name is ${myNane}`);
// tsc 報錯信息:
// Cannot find name 'myNane'. Did you mean 'myName'?
// eslint 報錯信息:
// 'myNane' is not defined.eslint(no-undef)
console.log(`My name is ${myName.toStrng()}`);
// tsc 報錯信息:
// Property 'toStrng' does not exist on type 'string'. Did you mean 'toString'?
```
| 存在的問題 | `tsc` 是否報錯 | `eslint` 是否報錯 |
| --- | --- | --- |
| 應該使用 `let` 或 `const` 而不是 `var` | ? | ? |
| `myName` 被誤寫成了 `myNane` | ? | ? |
| `toString` 被誤寫成了 `toStrng` | ?? | ? |
上例中,我們使用了 `var` 來定義一個變量,但其實 ES6 中有更先進的語法 `let` 和 `const`,此時就可以通過 `eslint` 檢查出來,提示我們應該使用 `let` 或 `const` 而不是 `var`。
對于未定義的變量 `myNane`,`tsc` 和 `eslint` 都可以檢查出來。
由于 `eslint` 無法識別 `myName` 存在哪些方法,所以對于拼寫錯誤的 `toString` 沒有檢查出來。
由此可見,`eslint` 能夠發現出一些 `tsc` 不會關心的錯誤,檢查出一些潛在的問題,所以代碼檢查還是非常重要的。
## 在 TypeScript 中使用 ESLint
### 安裝 ESLint
ESLint 可以安裝在當前項目中或全局環境下,因為代碼檢查是項目的重要組成部分,所以我們一般會將它安裝在當前項目中。可以運行下面的腳本來安裝:
```bash
npm install --save-dev eslint
```
由于 ESLint 默認使用 [Espree](https://github.com/eslint/espree) 進行語法解析,無法識別 TypeScript 的一些語法,故我們需要安裝 [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser),替代掉默認的解析器,別忘了同時安裝 `typescript`:
```bash
npm install --save-dev typescript @typescript-eslint/parser
```
接下來需要安裝對應的插件 [@typescript-eslint/eslint-plugin](https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin) 它作為 eslint 默認規則的補充,提供了一些額外的適用于 ts 語法的規則。
```bash
npm install --save-dev @typescript-eslint/eslint-plugin
```
### 創建配置文件
ESLint 需要一個配置文件來決定對哪些規則進行檢查,配置文件的名稱一般是 `.eslintrc.js` 或 `.eslintrc.json`。
當運行 ESLint 的時候檢查一個文件的時候,它會首先嘗試讀取該文件的目錄下的配置文件,然后再一級一級往上查找,將所找到的配置合并起來,作為當前被檢查文件的配置。
我們在項目的根目錄下創建一個 `.eslintrc.js`,內容如下:
```js
module.exports = {
parser: '@typescript-eslint/parser',
plugins: ['@typescript-eslint'],
rules: {
// 禁止使用 var
'no-var': "error",
// 優先使用 interface 而不是 type
'@typescript-eslint/consistent-type-definitions': [
"error",
"interface"
]
}
}
```
以上配置中,我們指定了兩個規則,其中 `no-var` 是 ESLint 原生的規則,`@typescript-eslint/consistent-type-definitions` 是 `@typescript-eslint/eslint-plugin` 新增的規則。
規則的取值一般是一個數組(上例中的 `@typescript-eslint/consistent-type-definitions`),其中第一項是 `off`、`warn` 或 `error` 中的一個,表示關閉、警告和報錯。后面的項都是該規則的其他配置。
如果沒有其他配置的話,則可以將規則的取值簡寫為數組中的第一項(上例中的 `no-var`)。
關閉、警告和報錯的含義如下:
- 關閉:禁用此規則
- 警告:代碼檢查時輸出錯誤信息,但是不會影響到 exit code
- 報錯:發現錯誤時,不僅會輸出錯誤信息,而且 exit code 將被設為 1(一般 exit code 不為 0 則表示執行出現錯誤)
### 檢查一個 ts 文件
創建了配置文件之后,我們來創建一個 ts 文件看看是否能用 ESLint 去檢查它。
創建一個新文件 `index.ts`,將以下內容復制進去:
```ts
var myName = 'Tom';
type Foo = {};
```
然后執行以下命令:
```bash
./node_modules/.bin/eslint index.ts
```
則會得到如下報錯信息:
```bash
/path/to/index.ts
1:1 error Unexpected var, use let or const instead no-var
3:6 error Use an `interface` instead of a `type` @typescript-eslint/consistent-type-definitions
? 2 problems (2 errors, 0 warnings)
2 errors and 0 warnings potentially fixable with the `--fix` option.
```
上面的結果顯示,剛剛配置的兩個規則都生效了:禁止使用 `var`;優先使用 `interface` 而不是 `type`。
需要注意的是,我們使用的是 `./node_modules/.bin/eslint`,而不是全局的 `eslint` 腳本,這是因為代碼檢查是項目的重要組成部分,所以我們一般會將它安裝在當前項目中。
可是每次執行這么長一段腳本頗有不便,我們可以通過在 `package.json` 中添加一個 `script` 來創建一個 npm script 來簡化這個步驟:
```json
{
"scripts": {
"eslint": "eslint index.ts"
}
}
```
這時只需執行 `npm run eslint` 即可。
### 檢查整個項目的 ts 文件
我們的項目源文件一般是放在 `src` 目錄下,所以需要將 `package.json` 中的 `eslint` 腳本改為對一個目錄進行檢查。由于 `eslint` 默認不會檢查 `.ts` 后綴的文件,所以需要加上參數 `--ext .ts`:
```json
{
"scripts": {
"eslint": "eslint src --ext .ts"
}
}
```
此時執行 `npm run eslint` 即會檢查 `src` 目錄下的所有 `.ts` 后綴的文件。
### 在 VSCode 中集成 ESLint 檢查
在編輯器中集成 ESLint 檢查,可以在開發過程中就發現錯誤,甚至可以在保存時自動修復錯誤,極大的增加了開發效率。
要在 VSCode 中集成 ESLint 檢查,我們需要先安裝 ESLint 插件,點擊「擴展」按鈕,搜索 ESLint,然后安裝即可。
VSCode 中的 ESLint 插件默認是不會檢查 `.ts` 后綴的,需要在「文件 => 首選項 => 設置 => 工作區」中(也可以在項目根目錄下創建一個配置文件 `.vscode/settings.json`),添加以下配置:
```json
{
"eslint.validate": [
"javascript",
"javascriptreact",
"typescript"
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
這時再打開一個 `.ts` 文件,將鼠標移到紅色提示處,即可看到這樣的報錯信息了:

我們還可以開啟保存時自動修復的功能,通過配置:
```json
{
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
},
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
就可以在保存文件后,自動修復為:
```ts
let myName = 'Tom';
interface Foo {}
```
### 使用 Prettier 修復格式錯誤
ESLint 包含了一些代碼格式的檢查,比如空格、分號等。但前端社區中有一個更先進的工具可以用來格式化代碼,那就是 [Prettier](https://prettier.io/)。
Prettier 聚焦于代碼的格式化,通過語法分析,重新整理代碼的格式,讓所有人的代碼都保持同樣的風格。
首先需要安裝 Prettier:
```bash
npm install --save-dev prettier
```
然后創建一個 `prettier.config.js` 文件,里面包含 Prettier 的配置項。Prettier 的配置項很少,這里我推薦大家一個配置規則,作為參考:
```js
// prettier.config.js or .prettierrc.js
module.exports = {
// 一行最多 100 字符
printWidth: 100,
// 使用 4 個空格縮進
tabWidth: 4,
// 不使用縮進符,而使用空格
useTabs: false,
// 行尾需要有分號
semi: true,
// 使用單引號
singleQuote: true,
// 對象的 key 僅在必要時用引號
quoteProps: 'as-needed',
// jsx 不使用單引號,而使用雙引號
jsxSingleQuote: false,
// 末尾不需要逗號
trailingComma: 'none',
// 大括號內的首尾需要空格
bracketSpacing: true,
// jsx 標簽的反尖括號需要換行
jsxBracketSameLine: false,
// 箭頭函數,只有一個參數的時候,也需要括號
arrowParens: 'always',
// 每個文件格式化的范圍是文件的全部內容
rangeStart: 0,
rangeEnd: Infinity,
// 不需要寫文件開頭的 @prettier
requirePragma: false,
// 不需要自動在文件開頭插入 @prettier
insertPragma: false,
// 使用默認的折行標準
proseWrap: 'preserve',
// 根據顯示樣式決定 html 要不要折行
htmlWhitespaceSensitivity: 'css',
// 換行符使用 lf
endOfLine: 'lf'
};
```
接下來安裝 VSCode 中的 Prettier 插件,然后修改 `.vscode/settings.json`:
```json
{
"files.eol": "\n",
"editor.tabSize": 4,
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
}
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
這樣就實現了保存文件時自動格式化并且自動修復 ESLint 錯誤。
需要注意的是,由于 ESLint 也可以檢查一些代碼格式的問題,所以在和 Prettier 配合使用時,我們一般會把 ESLint 中的代碼格式相關的規則禁用掉,否則就會有沖突了。
### 使用 AlloyTeam 的 ESLint 配置
ESLint 原生的規則和 `@typescript-eslint/eslint-plugin` 的規則太多了,而且原生的規則有一些在 TypeScript 中支持的不好,需要禁用掉。
這里我推薦使用 [AlloyTeam ESLint 規則中的 TypeScript 版本](https://github.com/AlloyTeam/eslint-config-alloy#typescript),它已經為我們提供了一套完善的配置規則,并且與 Prettier 是完全兼容的(eslint-config-alloy 不包含任何代碼格式的規則,代碼格式的問題交給更專業的 Prettier 去處理)。
安裝:
```bash
npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-alloy
```
在你的項目根目錄下創建 `.eslintrc.js`,并將以下內容復制到文件中即可:
```js
module.exports = {
extends: [
'alloy',
'alloy/typescript',
],
env: {
// 您的環境變量(包含多個預定義的全局變量)
// Your environments (which contains several predefined global variables)
//
// browser: true,
// node: true,
// mocha: true,
// jest: true,
// jquery: true
},
globals: {
// 您的全局變量(設置為 false 表示它不允許被重新賦值)
// Your global variables (setting to false means it's not allowed to be reassigned)
//
// myGlobal: false
},
rules: {
// 自定義您的規則
// Customize your rules
}
};
```
更多的使用方法,請參考 [AlloyTeam ESLint 規則](https://github.com/AlloyTeam/eslint-config-alloy)
### 使用 ESLint 檢查 tsx 文件
如果需要同時支持對 tsx 文件的檢查,則需要對以上步驟做一些調整:
#### 安裝 `eslint-plugin-react`
```bash
npm install --save-dev eslint-plugin-react
```
#### package.json 中的 scripts.eslint 添加 `.tsx` 后綴
```json
{
"scripts": {
"eslint": "eslint src --ext .ts,.tsx"
}
}
```
#### VSCode 的配置中新增 typescriptreact 檢查
```json
{
"files.eol": "\n",
"editor.tabSize": 4,
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.autoFixOnSave": true,
"eslint.validate": [
"javascript",
"javascriptreact",
{
"language": "typescript",
"autoFix": true
},
{
"language": "typescriptreact",
"autoFix": true
}
],
"typescript.tsdk": "node_modules/typescript/lib"
}
```
#### 使用 AlloyTeam ESLint 規則中的 TypeScript React 版本
[AlloyTeam ESLint 規則中的 TypeScript React 版本](https://github.com/AlloyTeam/eslint-config-alloy#typescript-react)
## Troubleshootings
### Cannot find module '@typescript-eslint/parser'
你運行的是全局的 eslint,需要改為運行 `./node_modules/.bin/eslint`。
### VSCode 沒有顯示出 ESLint 的報錯
1. 檢查「文件 => 首選項 => 設置」中有沒有配置正確
2. 檢查必要的 npm 包有沒有安裝
3. 檢查 `.eslintrc.js` 有沒有配置
4. 檢查文件是不是在 `.eslintignore` 中
如果以上步驟都不奏效,則可以在「文件 => 首選項 => 設置」中配置 `"eslint.trace.server": "messages"`,按 `Ctrl`+`Shift`+`U` 打開輸出面板,然后選擇 ESLint 輸出,查看具體錯誤。

### 為什么有些定義了的變量(比如使用 `enum` 定義的變量)未使用,ESLint 卻沒有報錯?
因為無法支持這種變量定義的檢查。建議在 `tsconfig.json` 中添加以下配置,使 `tsc` 編譯過程能夠檢查出定義了未使用的變量:
```json
{
"compilerOptions": {
"noUnusedLocals": true,
"noUnusedParameters": true
}
}
```
### 啟用了 noUnusedParameters 之后,只使用了第二個參數,但是又必須傳入第一個參數,這就會報錯了
第一個參數以下劃線開頭即可,參考 https://github.com/Microsoft/TypeScript/issues/9458
[ESLint]: https://eslint.org/
[typescript-eslint]: https://github.com/typescript-eslint/typescript-eslint
---
- [上一章:工程](README.md)
- [下一章:編譯選項](./compiler-options.md)