在 Cloud Functions 中使用 TypeScript

对于希望使用 TypeScript 编写函数的开发者,Cloud Functions 提供了两种支持方案:

  • 创建并配置 TypeScript 项目,然后在初始化 (firebase init functions) 时自动进行转译。
  • 利用部署前钩子在部署时将现有 TypeScript 源代码转译为 JavaScript。

按照本指南中的说明,您可以将现有 JavaScript 项目迁移至 TypeScript,并使用部署前钩子来转译源代码,以继续部署函数。 就编写函数而言,TypeScript 相比原版 JavaScript 有诸多优势:

  • TypeScript 支持最新的 JavaScript 功能(例如 async/await),简化了 promise 管理
  • 您编写代码时,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,添加一个用于构建您的 TypeScript 项目的 bash 脚本。例如:

     {
       "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

如果您有一个使用 JavaScript 初始化和开发的 Cloud Functions 项目,可以将其迁移到 TypeScript。强烈建议您在开始之前创建一个 git 检查点或以其他方式进行备份。

如需迁移现有的 JavaScript Cloud Functions 项目,请执行以下操作:

  1. 创建一个 git 检查点并保存现有 JavaScript 源代码文件的副本。
  2. 在项目目录中,运行 firebase init functions 并在系统提示选择函数编写语言时选择 TypeScript
  3. 除非您确定不再需要保留现有文件,否则当系统提示是否覆盖现有 package.json 文件时,请选择
  4. 删除目录 functions/src 中的 index.ts,将其替换为现有的源代码。
  5. 在初始化时创建的 tsconfig.json 文件中,设置编译器选项以允许使用 JavaScript:"allowJs": true
  6. 将您保存的 package.json 文件复制到 functions 目录中,并对其进行修改,将 "main" 设置为 "lib/index.js"
  7. 另外,在 package.json 中为 TypeScript 添加一个如下所示的 build 脚本:

     {
       "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 作为快捷方式运行;这些命令都运行 build 并提供/启动函数 shell。

TypeScript 项目的 Functions 日志

firebase deploy 期间,您的项目的 index.ts 将被转译为 index.js,也就是说,Cloud Functions 日志将输出 index.js 文件中的行号,而非您编写的代码。为了让您更方便地找到 index.ts 中对应的路径和行号,firebase deploy 会创建 functions/lib/index.js.map。您可以在您偏好的 IDE 中或通过节点模块使用此源代码映射文件。