在 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:start 或 firebase functions:shell 之前，请务必在函数目录内运行 npm run build。或者，将 npm run serve 或 npm 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 中或通过节点模块使用此源代码映射文件。