使用入门：编写、测试和部署您的第一批函数

开始使用 Cloud Functions 前，请先完成本教程。您将从必要的设置任务开始，直到完成两个相关函数的创建、测试和部署：

“添加消息”函数，用于提供一个接受文本值的网址，并将其写入 Cloud Firestore。
“转换为大写”函数，用于在进行 Cloud Firestore 写入时触发并将文本转换为大写。

我们为此示例选择了 Cloud Firestore 和由 HTTP 触发的 JavaScript 函数，部分原因是可以通过 Firebase Local Emulator Suite 对这些后台触发器进行全面测试。此工具集还支持 Realtime Database、PubSub、Auth 和 HTTP Callable 触发器。其他类型的后台触发器（如 Remote Config、TestLab 和 Analytics 触发器）都可以使用本页面中未介绍的其他工具集进行交互式测试。

本教程的以下各部分将详细介绍构建、测试和部署示例所需的步骤。如果您只想运行和检查代码，请跳转到查看完整的示例代码。

创建 Firebase 项目

在 Firebase 控制台中，点击添加项目。
- 如需将 Firebase 资源添加到现有 Google Cloud 项目，请输入该项目的名称或从下拉菜单中选择该项目。
- 如需创建新项目，请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。
  
  Firebase 会根据您提供的名称，为您的 Firebase 项目生成一个唯一 ID。如果您希望修改此项目 ID，必须立即修改，因为当 Firebase 为项目预配资源后，您将无法进行更改。如需详细了解 Firebase 如何使用项目 ID，请访问了解 Firebase 项目。
如果看到相关提示，请查看并接受 Firebase 条款。
点击继续。

（可选）为您的项目设置 Google Analytics，以便在使用下列 Firebase 产品时能获得最佳体验：

选择现有的 Google Analytics 账号，或者创建一个新账号。

如果您选择创建一个新账号，请选择 Analytics 报告位置，然后接受项目的数据共享设置和 Google Analytics 条款。

点击创建项目（或者，如果您使用的是现有 Google Cloud 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中该 Firebase 项目的概览页面。

设置 Node.js 和 Firebase CLI

您需要使用 Node.js 环境来编写函数，并且需要使用 Firebase CLI 将函数部署到 Cloud Functions 运行时。建议您使用 Node Version Manager 来安装 Node.js 和 npm。

安装 Node.js 和 npm 后，您就可以使用自己偏好的方法来安装 Firebase CLI。如需通过 npm 安装 CLI，请使用以下命令：

npm install -g firebase-tools

这会安装全局可用的 Firebase 命令。如果命令失败，您可能需要更改 npm 权限。如需更新到最新版本的 firebase-tools，请重新运行这一命令。

初始化您的项目

初始化 Firebase SDK for Cloud Functions 时，您需要创建一个空项目（其中包含依赖项和一些少量的示例代码），并选择 TypeScript 或 JavaScript 来编写函数。在本教程中，您还需要初始化 Cloud Firestore。

如需初始化您的项目，请执行以下操作：

运行 firebase login，通过浏览器登录并对 Firebase CLI 进行身份验证。
转到 Firebase 项目目录。
运行 firebase init firestore。在本教程中，当系统提示您选择 Firestore 规则和索引文件时，您可以接受默认值。如果您尚未在此项目中使用 Cloud Firestore，则还需要按照 Cloud Firestore 使用入门中的说明为 Firestore 选择开始模式和位置。
运行 firebase init functions。CLI 会提示您选择现有的代码库，或者初始化并命名新的代码库。刚开始使用时，默认位置中的单个代码库就足够了；稍后，随着您工作的扩展，您可能需要在代码库中整理函数。
CLI 支持两种语言：
- JavaScript
- TypeScript 如需了解详情，请参阅使用 TypeScript 编写函数。
在本教程中，选择 JavaScript。
CLI 会为您提供使用 npm 安装依赖项的选项。如果您希望通过其他方式管理依赖项，可以放心地拒绝此选项；但如果拒绝，则需要在模拟或部署函数之前运行 npm install。

这些命令成功完成后，您的项目结构应如下所示：

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

初始化期间创建的 package.json 文件包含一个重要的键："engines": {"node": "16"}。它指定了用于编写和部署函数的 Node.js 版本。您可以选择其他受支持的版本。

导入所需的模块并初始化应用

完成设置任务后，您可以打开源代码目录，并按照以下各部分的说明开始添加代码。在此示例中，您的项目必须使用 Node require 语句导入 Cloud Functions 和 Admin SDK 模块。请将如下代码行添加到您的 index.js 文件中：

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();index.js

这些行会加载 firebase-functions 和 firebase-admin 模块，并初始化一个您可以在其中进行 Cloud Firestore 更改的 admin 应用实例。与 FCM、Authentication 和 Firebase Realtime Database 一样，在支持 Admin SDK 的所有环境中，都提供了一种使用 Cloud Functions 来集成 Firebase 的强大方法。

当您初始化项目时，Firebase CLI 会自动安装 Firebase 和 Firebase SDK for Cloud Functions 这两个 Node 模块。如需将第三方库添加到项目中，您可以修改 package.json 并运行 npm install。如需了解详情，请参阅处理依赖项。

添加 `addMessage()` 函数

如需添加 addMessage() 函数，请将下面几行代码添加到 index.js：

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});index.js

addMessage() 函数是一个 HTTP 端点。向端点发送的任何请求都会导致将 ExpressJS 样式的 Request 和 Response 对象传递给 onRequest() 回调函数。

HTTP 函数是同步函数（类似于 Callable 函数），因此您应该尽快发送响应并推迟使用 Cloud Firestore 的工作。addMessage() HTTP 函数将文本值传递到 HTTP 端点，并将其插入数据库中的 /messages/:documentId/original 路径下。

添加 `makeUppercase()` 函数

如需添加 makeUppercase() 函数，请将下面几行代码添加到 index.js：

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });index.js

makeUppercase() 函数在有数据写入 Cloud Firestore 时执行。ref.set 函数定义要监听的文档。考虑到性能原因，定义应尽可能具体。

大括号可用于括住“参数”（例如 {documentId}），即在回调函数中提供其匹配数据的通配符。

每当添加了新消息时，Cloud Firestore 都会触发 onCreate() 回调函数。

事件驱动型函数（如 Cloud Firestore 事件）是异步的。回调函数应返回 null、一个对象或一个 Promise。如果您不返回任何结果，函数就会超时，示意发生错误，然后重试。请参阅同步、异步和 Promise。

模拟函数的执行

借助 Firebase Local Emulator Suite，您可以在本地机器上构建和测试应用，而无需部署到 Firebase 项目。我们强烈建议在开发期间进行本地测试，部分原因是可以降低因代码错误（例如无限循环）而在生产环境中产生费用的风险。

如需模拟函数，请执行以下操作：

运行 firebase emulators:start 并检查 Emulator Suite UI 的网址输出。它默认为 localhost:4000，但可以托管在您机器的其他端口上。在浏览器中输入该网址，以打开 Emulator Suite UI。
检查 firebase emulators:start 命令的输出，查找 HTTP 函数 addMessage() 的网址。它看起来类似于 http://localhost:5001/MY_PROJECT/us-central1/addMessage，不同之处在于：
1. MY_PROJECT 将被替换为您的项目 ID。
2. 您的本地机器上的端口可能不同。
将查询字符串 ?text=uppercaseme 添加到函数网址的末尾，其格式应类似于 http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme。（可选）您可以将消息“uppercaseme”更改为自定义消息。
在浏览器的新标签页中打开该网址，创建一条新消息。
在 Emulator Suite UI 中查看函数的效果：
1. 在日志标签页中，您应该会看到表示函数 addMessage() 和 makeUppercase() 运行的新日志：
  
  i functions: Beginning execution of "addMessage"
  
  i functions: Beginning execution of "makeUppercase"
2. 在 Firestore 标签页中，您应该会看到包含原始消息及此消息的大写版本（如果最初是“uppercaseme”，则显示“UPPERCASEME”）的文档。

将函数部署到生产环境

函数在模拟器中按预期工作后，您就可以继续执行后续步骤，在生产环境中部署、测试和运行这些函数。请注意，如需部署到推荐的 Node.js 14 运行时环境，您的项目必须采用 Blaze 定价方案。请参阅 Cloud Functions 价格。

如需完成本教程，请部署您的函数，然后执行 addMessage() 以触发 makeUppercase()。

运行以下命令部署您的函数：
```
 firebase deploy --only functions
 
```
运行此命令后，Firebase CLI 会输出任何 HTTP 函数端点的网址。在您的终端中，您应该会看到如下所示的一行输出：
```
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
```
该网址包含您的项目 ID 以及 HTTP 函数的区域。虽然您现在还用不着考虑这一点，但一些生产 HTTP 函数应指定位置以尽可能缩短网络延迟时间。

如果遇到访问错误，例如“Unable to authorize access to project”（无法授予项目访问权限），请尝试检查您的项目别名。
使用 CLI 输出的 addMessage() 网址，添加文本查询参数，并在浏览器中打开该网址：
```
https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
```
函数就会执行，并将浏览器重定向到 Firebase 控制台中存储着该文本字符串的数据库位置。这一写入事件触发了 makeUppercase()，后者将写入该字符串的大写形式。

部署和执行函数后，您可以在 Google Cloud 控制台中查看日志。如果您需要在开发或生产环境中删除函数，请使用 Firebase CLI。

在生产环境中，您可能希望设置要运行的实例数下限和上限，以优化函数性能并控制费用。如需详细了解这些运行时选项，请参阅控制扩缩行为。

查看完整的示例代码

下面是包含函数 addMessage() 和 makeUppercase() 的完整 functions/index.js。这些函数允许您向 HTTP 端点传递一个参数，端点会向 Cloud Firestore 写入一个值，然后转换该值，将字符串中的所有字符改为大写。

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });index.js

后续步骤

在此文档中，您可以详细了解如何为 Cloud Functions 管理函数，以及如何处理 Cloud Functions 支持的所有事件类型。

如需详细了解 Cloud Functions，您还可以：