針對 Cloud Functions 使用 TypeScript

對於偏好使用 TypeScript 編寫函式的開發人員,Cloud Functions 提供兩種支援類型:

  • 建立及設定 TypeScript 專案,以便在初始化時自動翻譯 (firebase init functions)。
  • 在部署時透過預先部署掛鉤,將現有的 TypeScript 來源轉譯為 JavaScript。

您可以按照本指南中的操作說明,將現有的 JavaScript 專案遷移至 TypeScript,然後繼續透過預先部署掛鉤部署函式,以轉譯原始碼。編寫函式時,TypeScript 比一般 JavaScript 有許多好處:

  • TypeScript 支援 async/await 等最新的 JavaScript 功能,簡化承諾管理
  • Cloud Functions Linter 會在編寫程式碼時醒目顯示常見問題
  • 類型安全機制有助於避免已部署函式的執行階段錯誤

如果您是第一次使用 TypeScript,請參閱「5 分鐘內輸入 TypeScript」。

使用 TypeScript 初始化新的 Cloud Functions 專案

在新目錄中執行 firebase init functions。這項工具提供使用 JavaScript 或 TypeScript 建構專案的選項。選擇「TypeScript」以輸出下列專案結構:

myproject
 +- functions/     # Directory containing all your functions code
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- tsconfig.json
      |
      +- .eslintrc.js # Optional file if you enabled ESLint
      +- tsconfig.dev.json # Optional file that references .eslintrc.js
      |
      +- src/     # Directory containing TypeScript source
      |   |
      |   +- index.ts  # main source file for your Cloud Functions code
      |
      +- lib/
          |
          +- index.js  # Built/transpiled JavaScript code
          |
          +- index.js.map # Source map for debugging

初始化完成後,請將 index.ts 中的範例取消註解並執行 npm run serve,查看「Hello World」函式的應用實例。

使用現有的 TypeScript 專案

如果您已有 TypeScript 專案,可以新增預先部署掛鉤,確保每次將程式碼部署至 Cloud Functions for Firebase 時,都能轉譯專案。您需要具備格式正確的 tsconfig.json 檔案和 Firebase 專案,且需要對 Firebase 設定進行以下修改:

  1. 編輯 package.json,新增 bash 指令碼來建構 TypeScript 專案。例如:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  2. 編輯 firebase.json,新增預先部署掛鉤以執行建構指令碼。例如:

     {
       "functions": {
         "predeploy": "npm --prefix functions run build",
       }
     }
    

透過這項設定,firebase deploy --only functions 指令會建構 TypeScript 程式碼,並將其部署為函式。

將現有 JavaScript 專案遷移至 TypeScript

如果您目前已有 Cloud Functions 專案,並且已在 JavaScript 中初始化及開發,可將其遷移至 TypeScript。強烈建議您在開始之前,先建立 Git 檢查點或其他備份。

如何遷移現有的 JavaScript Cloud Functions 專案:

  1. 建立 Git 檢查點並儲存現有 JavaScript 來源檔案的副本。
  2. 在專案目錄中,執行 firebase init functions,並在系統顯示編寫函式語言的提示時,選取 TypeScript
  3. 當系統提示您覆寫現有的 package.json 檔案時,除非您確定不要保留現有檔案,否則請選取「No」
  4. 刪除 functions/src 目錄中的 index.ts,並替換為現有的原始碼。
  5. 在初始化時建立的 tsconfig.json 檔案中,將編譯器選項設為允許 JavaScript:"allowJs": true
  6. 將儲存的 package.json 檔案複製到 functions 目錄,然後編輯該檔案,將 "main" 設為 "lib/index.js"
  7. 此外,在 package.json 中,新增 TypeScript 的建構指令碼,如下所示:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  8. 執行 npm install --save-dev typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser,將 "typescript" 新增為開發依附元件。

  9. 針對所有依附元件,請執行 npm install --save @types/<dependency>

  10. 視需要將原始碼從 .js 改寫為 .ts。

模擬 TypeScript 函式

如要在本機測試 TypeScript 函式,您可以使用「在本機執行函式」一文所述的模擬工具。使用這些工具前,請務必先編譯程式碼,因此在執行 firebase emulators:startfirebase functions:shell 之前,請務必在函式目錄中執行 npm run build。或者,您也可以執行 npm run servenpm run shell 做為捷徑,這些指令都會執行建構並提供/啟動函式殼層。

TypeScript 專案的函式記錄檔

firebase deploy 期間,系統會將專案的 index.ts 轉譯為 index.js,這表示 Cloud Functions 記錄檔會輸出 index.js 檔案中的行數,而不是您編寫的程式碼。為方便您在 index.ts 中找出對應的路徑和行數,firebase deploy 會建立 functions/lib/index.js.map。您可以在偏好的 IDE 或透過節點模組使用這個來源對應。