超全面的前端工程化配置指南

語言: CN / TW / HK

點擊上方  前端進階之旅 ,關注公眾號

>>前端求職面試刷題神器<<

作者:molvqingtai

原文鏈接: https://juejin.cn/post/6971812117993226248

前端工程化配置指南

本文講解如何構建一個工程化的前端庫,並結合 Github Actions ,自動發佈到 GithubNPM 的整個詳細流程。

示例

我們經常看到像 VueReact 這些流行的開源項目有很多配置文件,他們是幹什麼用的?他們的 Commit、Release 記錄都那麼規範,是否基於某種約定?

廢話少説,先上圖!

上圖標紅就是相關的工程化配置,有 Linter、Tests,Github Actions 等,覆蓋開發、測試、發佈的整個流程。

相關配置清單

  • Eslint

  • Prettier

  • Commitlint

  • Husky

  • Jest

  • GitHub Actions

  • Semantic Release

下面我們從創建一個 TypeScript 項目開始,一步一步完成所有的工程化配置,並説明每個配置含義以及容易踩的坑。

初始化

為了避免兼容性問題,建議先將 node 升級到最新的長期支持版本。

首先在 Github 上創建一個 repo,拉下來之後通過 npm init -y 初始化。然後創建 src 文件夾,寫入 index.ts

package.json 生成之後,我需要添加如下配置項:

   "main": "index.js",
+  "type": "module",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "publishConfig": {
+    "access": "public"
+  }

我們將項目定義為 ESM 規範,前端社區正逐漸向 ESM 標準遷移,從 Node v12.0.0 開始,只要設置了 "type": "module" , Node 會將整個項目視為 ESM 規範,我們就可以直接寫裸寫 import/export

publishConfig.access 表示當前項目發佈到 NPM 的訪問級別,它有 restrictedpublic 兩個選項, restricted 表示我們發佈到 NPM 上的是私有包(收費),訪問級別默認為 restricted ,因為我們是開源項目所以標記為 public

配置

創建項目之後,我們開始安裝工程化相關的依賴,因為我們是 TypeScript 項目,所以也需要安裝 TypeScript 的依賴。

Typescript

先安裝 TypeScript,然後使用 tsc 命名生成 tsconfig.json

npm i typescript -D
npx tsc --init

然後我們需要添加修改 tsconfig.json 的配置項,如下:

{
  "compilerOptions": {
    /* Basic Options */
    "baseUrl": ".", // 模塊解析根路徑,默認為 tsconfig.json 位於的目錄
    "rootDir": "src", // 編譯解析根路徑,默認為 tsconfig.json 位於的目錄
    "target": "ESNEXT", // 指定輸出 ECMAScript 版本,默認為 es5
    "module": "ESNext", // 指定輸出模塊規範,默認為 Commonjs
    "lib": ["ESNext", "DOM"], // 編譯需要包含的 API,默認為 target 的默認值
    "outDir": "dist", // 編譯輸出文件夾路徑,默認為源文件同級目錄
    "sourceMap": true, // 啟用 sourceMap,默認為 false
    "declaration": true, // 生成 .d.ts 類型文件,默認為 false
    "declarationDir": "dist/types", // .d.ts 類型文件的輸出目錄,默認為 outDir 目錄
    /* Strict Type-Checking Options */
    "strict": true, // 啟用所有嚴格的類型檢查選項,默認為 true
    "esModuleInterop": true, // 通過為導入內容創建命名空間,實現 CommonJS 和 ES 模塊之間的互操作性,默認為 true
    "skipLibCheck": true, // 跳過導入第三方 lib 聲明文件的類型檢查,默認為 true
    "forceConsistentCasingInFileNames": true, // 強制在文件名中使用一致的大小寫,默認為 true
    "moduleResolution": "Node", // 指定使用哪種模塊解析策略,默認為 Classic
  },
  "include": ["src"] // 指定需要編譯文件,默認當前目錄下除了 exclude 之外的所有.ts, .d.ts,.tsx 文件
} 

更多詳細配置參考: www.typescriptlang.org/tsconfig

注意的點,如果你的項目涉及到 WebWorker API ,需要添加到 lib 字段中

"lib": ["ESNext", "DOM", "WebWorker"],

然後我們將編譯後的文件路徑添加到 package.json ,並在 scripts 中添加編譯命令。

-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/types/index.d.ts"
   "type": "module",
-   "scripts": {
-     "test": "echo \"Error: no test specified\" && exit 1"
-   },
+   "scripts": {
+     "dev": "tsc --watch",
+     "build": "npm run clean && tsc",
+     "clean": "rm -rf dist"
+  },
   "publishConfig": {
     "access": "public"
   }

types 配置項是指定編譯生成的類型文件,如果 compilerOptions.declarationDir 指定的是 dist ,也就是源碼和 .d.ts 同級,那麼 types 可以省略。

驗證配置是否生效,在 index.ts 寫入

const calc = (a: number, b: number) => {
  return a - b
}
console.log(calc(1024, 28))

在控制枱中執行

npm run build && node dist/index.js

會在 dist 目錄中生成 types/index.d.tsindex.jsindex.js.map ,並打印 996

Eslint & Prettier

代碼規範離不開各種 Linter , 之所以把這兩個放在一起講,借用 Prettier 官網的一句話: “使用 Prettier 解決代碼格式問題,使用 linters 解決代碼質量問題” 。雖然 eslint 也有格式化功能,但是 prettier 的格式化功能更強大。

大部分同學編輯器都裝了 prettier-vscodeeslint-vscode 這兩個插件,如果你項目只有其中一個的配置,因為這兩者部分格式化的功能有差異,那麼就會造成一個的問題,代碼分別被兩個插件分別格式化一次,網上解決 prettier + eslint 衝突的方案五花八門,甚至還有把整個 rules 列表貼出來的。

那這裏我們按照官方推薦,用最少的配置去解決 prettiereslint 的集成問題。

Eslint

首先安裝 eslint ,然後利用 eslint 的命令行工具生成基本配置。

npm i eslint -D
npx eslint --init

執行上面命令後會提示一些選項,我們依次選擇符合我們項目的配置。

注意,這裏 eslint 推薦了三種社區主流的規範, AirbnbStandardGoogle ,因個人愛好我選擇了不寫分號的 Standard 規範。

生成的 .eslintrc.cjs 文件應該長這樣

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'standard'
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 12,
    sourceType: 'module'
  },
  plugins: [
    '@typescript-eslint'
  ],
  rules: {
  }
}

有些同學可能就要問了,這裏為什麼生成的配置文件名稱是 .eslintrc.cjs 而不是 .eslintrc.js

因為我們將項目定義為 ESMeslit --init 會自動識別 type ,並生成兼容的配置文件名稱,如果我們改回 .js 結尾,再運行 eslint 將會報錯。出現這個問題是 eslint 內部使用了 require() 語法讀取配置。

同樣,這個問題也適用於其他功能的配置,比如後面會講到的 PrettierCommitlint 等,配置文件都不能以 xx.js 結尾,而要改為當前庫支持的其他配置文件格式,如: .xxrc.xxrc.json.xxrc.yml

驗證配置是否生效,修改 index.ts

  const calc = (a: number, b: number) => {
    return a - b
  }
- console.log(calc(1024, 28))
+ // console.log(calc(1024, 28))

package.json 中添加 lint 命令

  "scripts": {
    "dev": "tsc --watch",
    "build": "npm run clean && tsc",
+   "lint": "eslint src --ext .js,.ts --cache --fix",
    "clean": "rm -rf dist"
  },

然後在控制枱執行 lint , eslint 將會提示 1 條錯誤信息,説明校驗生效。

npm run lint
# 1:7  error  'calc' is assigned a value but never used  no-unused-vars

因為是 Typescript 項目所以我們還要添加 Standard 規範提供的 TypeScrip 擴展配置(其他規範同理)

安裝 eslint-config-standard-with-typescript

npm i eslint-config-standard-with-typescript -D

添加修改 .eslintrc.cjs

    module.exports = {
      env: {
        browser: true,
        es2021: true,
        node: true
      },
-     extends: ['standard']
+     extends: ['standard', 'eslint-config-standard-with-typescript'],
      parser: '@typescript-eslint/parser',
      parserOptions: {
        ecmaVersion: 12,
        sourceType: 'module',
+       project: './tsconfig.json'
      },
      plugins: ['@typescript-eslint'],
      rules: {}
    }

驗證配置是否生效

在控制枱執行 lint , eslint 將會提示 2 條錯誤信息,説明校驗生效。

npm run lint
# 1:7  error  'calc' is assigned a value but never used  no-unused-vars
# 1:14 error  Missing return type on function 

Prettier

現在我們按照官網的推薦方式,把 prettier 集成到 eslint 的校驗中。

安裝 prettier 並初始化配置文件

npm i prettier -D
echo {}> .prettierrc.json

然後在 .prettierrc.json 添加配置,這裏只需要添加和你所選規範衝突的部分。

{
  "semi": false, // 是否使用分號
  "singleQuote": true, // 使用單引號代替雙引號
  "trailingComma": "none" // 多行時儘可能使用逗號結尾
}

更多配置詳見: prettier.io/docs/en/opt…

安裝解決衝突需要用到的兩個依賴

  • eslint-config-prettier 關閉可能與 prettier 衝突的規則
  • eslint-plugin-prettier 使用 prettier 代替 eslint 格式化
npm i eslint-config-prettier eslint-plugin-prettier -D

再添加修改 .eslintrc.cjs ,如下:

  module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
- extends: ['standard', 'eslint-config-standard-with-typescript'],
+ extends: ['standard', 'eslint-config-standard-with-typescript', 'prettier'],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 12,
    sourceType: 'module',
    project: './tsconfig.json',
  },
- plugins: ['@typescript-eslint'],
+ plugins: ['@typescript-eslint', 'prettier'],
- rules: {},
+ rules: {
+   'prettier/prettier': 'error'
+ },
}

然後驗證配置是否生效,修改 index.ts

-  const calc = (a: number, b: number) => {
+  const calc = (a: number, b: number): number => {
    return a - b
  }
- // console.log(calc(1024, 28))
+ console.log(calc(1024, 28))

然後在控制枱執行 lint ,這裏 prettiereslint 的行為已保持一致,如果沒有報錯,那就成功了。

npm run lint

我們現在已經完成了 eslintprettier 的集成配置。和編輯器無關,也就是説無論你使用什麼編輯器,有沒有安裝相關插件,都不會影響代碼校驗的效果。

Husky

因為一個項目通常是團隊合作,我們不能保證每個人在提交代碼之前執行一遍 lint 校驗,所以需要 git hooks 來自動化校驗的過程,否則禁止提交。

安裝 Husky 並生成 .husky 文件夾

npm i husky -D
npx husky install

然後我們需要在每次執行 npm install 時自動啟用 husky

如果你的 npm 版本大於等於 7.1.0

npm set-script prepare "husky install"

否則手動在 package.json 中添加

 "scripts": {
    "dev": "tsc --watch",
    "build": "npm run clean && tsc",
    "lint": "eslint src --ext .js,.ts --cache --fix",
    "clean": "rm -rf dist",
+   "prepare": "husky install"
  },

然後添加一個 lint 鈎子

npx husky add .husky/pre-commit "npm run lint"

相當於手動在 .husky/pre-commit 文件寫入以下內容:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npm run lint

測試鈎子是否生效,修改 index.ts

  const calc = (a: number, b: number): number => {
    return a - b
  }
- console.log(calc(1024, 28))
+ // console.log(calc(1024, 28))

然後提交一條 commit ,如果配置正確將會自動執行 lint 並提示 1 條錯誤信息, commit 提交將會失敗。

git add .
git commit -m 'test husky'
# 1:7  error  'calc' is assigned a value but never used

Commitlint

為什麼需要 Commitlint ,除了在後續的生成 changelog 文件和語義發版中需要提取 commit 中的信息,也利於其他同學分析你提交的代碼,所以我們要約定 commit 的規範。

安裝 Commitlint

  • @commitlint/cli Commitlint 命令行工具

  • @commitlint/config-conventional 基於 Angular 的約定規範

npm i @commitlint/config-conventional @commitlint/cli -D

最後將 Commitlint 添加到鈎子

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

創建 .commitlintrc ,並寫入配置

{
  "extends": [
    "@commitlint/config-conventional"
  ]
}

注意,這裏配置文件名使用的是 .commitlintrc 而不是默認的 .commitlintrc.js ,詳見 Eslint 章節

測試鈎子是否生效,修改 index.ts ,讓代碼正確

  const calc = (a: number, b: number): void => {
    console.log(a - b)
  }
- // calc(1024, 28)
+ calc(1024, 28)

提交一條不符合規範的 commit ,提交將會失敗

git add .
git commit -m 'add eslint and commitlint'

修改為正確的 commit ,提交成功!

git commit -m 'ci: add eslint and commitlint'

Angular 規範説明:

  • feat :新功能

  • fix :修補 BUG

  • docs :修改文檔,比如 README, CHANGELOG, CONTRIBUTE 等等

  • style :不改變代碼邏輯 (僅僅修改了空格、格式縮進、逗號等等)

  • refactor :重構(既不修復錯誤也不添加功能)

  • perf :優化相關,比如提升性能、體驗

  • test :增加測試,包括單元測試、集成測試等

  • build :構建系統或外部依賴項的更改

  • ci :自動化流程配置或腳本修改

  • chore :非 src 和 test 的修改,發佈版本等

  • revert :恢復先前的提交

Jest

美好生活從測試覆蓋率 100% 開始。

安裝 jest ,和類型聲明 @types/jest ,它執行需要 ts-nodets-jest

這裏暫時固定了 ts-node 的版本為 v9.1.1 ,新版的 [email protected] 會導致 jest 報錯,等待官方修復,詳見: issues

npm i jest @types/jest [email protected] ts-jest -D

初始化配置文件

npx jest --init

然後修改 jest.config.ts 文件

   // A preset that is used as a base for Jest's configuration
-  // preset: undefined,
+  preset: 'ts-jest'

將測試命令添加到 package.json 中。

  "scripts": {
    "dev": "tsc --watch",
    "build": "npm run clean && tsc",
    "lint": "eslint src --ext .js,.ts --cache --fix",
    "clean": "rm -rf dist",
    "prepare": "husky install",
+   "test": "jest"
  },

創建測試文件夾 __tests__ 和測試文件 __tests__/calc.spec.ts

修改 index.ts

  const calc = (a: number, b: number): number => {
    return a - b
  }
- // console.log(calc(1024, 28))
+ export default calc

然後在 calc.spec.ts 中寫入測試代碼

import calc from '../src'

test('The calculation result should be 996.', () => {
  expect(calc(1024, 28)).toBe(996)
})

驗證配置是否生效

在控制枱執行 test ,將會看到測試覆蓋率 100% 的結果。

npm run test

最後我們給 __tests__ 目錄也加上 lint 校驗

修改 package.json

  "scripts": {
    "dev": "tsc --watch",
    "build": "npm run clean && tsc",
-   "lint": "eslint src --ext .js,.ts --cache --fix",
+   "lint": "eslint src __tests__ --ext .js,.ts --cache --fix",
    "clean": "rm -rf dist",
    "prepare": "husky install",
    "test": "jest"
  },

這裏如果我們直接執行 npm run lint 將會報錯,提示 __tests__ 文件夾沒有包含在 tsconfig.jsoninclude 中,當我們添加到 include 之後,輸出的 dist 中就會包含測試相關的文件,這並不是我們想要的效果。

我們使用 typescript-eslint 官方給出的解決方案,如下操作:

新建一個 tsconfig.eslint.json 文件,寫入以下內容:

{
  "extends": "./tsconfig.json",
  "include": ["**/*.ts", "**/*.js"]
}

.eslintrc.cjs 中修改

  parserOptions: {
    ecmaVersion: 12,
    sourceType: 'module',
-   project: './tsconfig.json'
+   project: './tsconfig.eslint.json'
  },

然後驗證配置是否生效,直接提交我們添加的測試文件,能正確提交説明配置成功。

git add .
git commit -m 'test: add unit test'

Github Actions

我們通過 Github Actions 實現代碼合併或推送到主分支, dependabot 機器人升級依賴等動作,會自動觸發測試和發佈版本等一系列流程。

在項目根目錄創建 .github/workflows 文件夾,然後在裏面新建 ci.yml 文件和 cd.yml 文件

ci.yml 文件中寫入:

name: CI

on:
  push:
    branches:
      - '**'
  pull_request:
    branches:
      - '**'
jobs:
  linter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
      - run: npm ci
      - run: npm run lint
  tests:
    needs: linter
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
      - run: npm ci
      - run: npm run test

上面配置大概意思就是,監聽所有分支的 pushpull_request 動作,自動執行 lintertests 任務。

GithubActions 更多用法參考: github.com/features/ac…

然後推送代碼,驗證配置是否生效

git add .
git commit -m 'ci: use github actions'
git push

此時打開當前項目的 Github 頁面,然後點擊頂部 Actions 菜單就會看到正在進行的兩個任務,一個將會成功(測試),一個將會失敗(發佈)。

上面只是實現了代碼自動測試流程,下面實現自動發佈的流程。

在此之前需要到 NPM 網站上註冊一個賬號(已有可忽略),並創建一個 package

然後創建 GH_TOKENNPM_TOKEN (注意,不要在代碼中包含任何的 TOKEN 信息):

  • 如何創建 GITHUB\_TOKEN (創建時勾選 repoworkflow 權限)

  • 如何創建 NPM\_TOKEN (創建時選中 Automation 權限)

將創建好的兩個 TOKEN 添加到項目的 Actions secrets 中:

Github 項目首頁 -> 頂部 Settings 菜單 -> 側邊欄 Secrets

然後修改 package.json 中的 “name”“name” 就是你在 NPM 上創建的 package 的名稱。

cd.yml 文件中寫入:

name: CD

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 16
      # https://github.com/semantic-release/git/issues/209
      - run: npm ci --ignore-scripts
      - run: npm run build
      - run: npx semantic-release
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

由於“黑命貴”,Github 已將新項目的默認分支名稱更改為 “main” ,詳見: issues , 為了方便,後面統一稱為 主分支

所以如果你的主分支名稱是 “main” ,上面的 branches 需要修改為:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

然後安裝語義發版依賴,需要用到 semantic-release 和它的插件:

  • semantic-release :語義發版核心庫

  • @semantic-release/changelog :用於自動生成 changelog.md

  • @semantic-release/git :用於將發佈時產生的更改提交回遠程倉庫

npm i semantic-release @semantic-release/changelog @semantic-release/git -D

在項目根目錄新建配置文件 .releaserc 並寫入:

{
  "branches": ["master"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/github",
    "@semantic-release/npm",
    "@semantic-release/git"
  ]
}

這裏同樣,如果你的主分支名稱是 “main” ,上面的 branches 需要修改為:

  "branches": ["+([0-9])?(.{+([0-9]),x}).x", "main"],

最後新建分支 develop 分支並提交工作內容。

git checkout -b develop
git add .
git commit -m 'feat: complete the CI/CD workflow'
git push --set-upstream origin develop
git push

然後將 develop 分支合併到 主分支 ,並提交,注意:這個提交會觸發測試並 發佈版本 (自動創建 tagchangelog )

git checkout master
git merge develop
git push

完成上面操作之後,打開 Github 項目主頁NPM 項目主頁 可以看到一個 Release 的更新記錄。

最後切回到 develop 分支,創建一個自動更新依賴的 workflow

.github 文件夾中創建 dependabot.yml 文件,並寫入內容:

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: 'npm'
    # Look for `package.json` and `lock` files in the `root` directory
    directory: '/'
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: 'weekly'

提交併查看 workflows 是否全部通過,再合併到 主分支 並提交,這個提交不會觸發版本發佈。

git pull origin master
git add .
git commit -m 'ci: add dependabot'
git push 

git checkout master
git merge develop
git push

觸發版本發佈需要兩個條件:

  1. 只有當 pushpull_request主分支 上才會觸發版本發佈
  2. commit
    feat
    fix
    perf
    

更多發佈規則,詳見: github.com/semantic-re…

SemanticRelease 使用方式,詳見: semantic-release.gitbook.io

如果你能正確配置上面所有步驟,併成功發佈,那麼恭喜你!你擁有了一個完全自動化的項目,它擁有:自動依賴更新、測試、發佈,和自動生成版本信息等功能。

完整的項目示例: @resreq/event-hub

結語

本文未涉及到:組件庫、Monorepo、Jenkins CI 等配置,但能覆蓋絕大部前端項目 CI/CD 流程。

有些地方講得比較細,甚至有些囉嗦,但還是希望能幫助到大家!撒花!:tada::tada::tada:

寫在最後

歡迎添加poetry 微信poetries4070 我會第一時間和你分享前端行業趨勢,學習途徑,成長內容等,2022年陪你一起度過!

如果你覺得這篇內容對你有幫助,我想請你幫我3個小忙:

1.  訂閲前端面試寶典   interview2.poetries.top   讓我們成為長期關係,共同成長。

2.  訂閲編程導航   nav.poetries.top   整理了大量免費的編程學習資源。

3.  領取精心為您整理的前端面試資料

>>前端面試求職刷題神器<