将应用连接到 Cloud Functions 模拟器

Beta 版。此模拟器目前处于 Beta 版阶段。它可能会以不向后兼容的方式更改，我们一如既往地衷心期待您的反馈。如果您有任何想法，请告知我们！

在将您的应用连接到 Cloud Functions 模拟器之前，请确保您了解 Firebase Local Emulator Suite 的整体工作流，而且已安装和配置 Local Emulator Suite 并已查看其 CLI 命令。

选择一个 Firebase 项目

Firebase Local Emulator Suite 模拟的是单个 Firebase 项目的产品。

如需选择要使用的项目，请在启动模拟器之前，使用 CLI 在工作目录下运行 firebase use。或者，您可以将 --project 标志传递给每个模拟器命令。

注意：通常情况下，最好为所有模拟器调用使用同一个项目 ID，让 Emulator Suite 界面、不同的产品模拟器以及特定模拟器的所有正在运行的实例在任何情况下都可以正确通信。事实上，默认情况下，Local Emulator Suite 会在检测到多个正在使用的项目 ID 时发出警告，但您可以覆盖此行为。如需了解如何设置和管理项目 ID，请参阅安装和配置指南。

Local Emulator Suite 支持模拟实际 Firebase 项目和演示项目。

项目类型	特性	与模拟器结合使用
实际项目	实际 Firebase 项目就是您创建和配置的项目（很可能是通过 Firebase 控制台创建和配置）。 实际项目具有实时资源，例如数据库实例、存储桶、函数或您为该 Firebase 项目设置的任何其他资源。	使用实际的 Firebase 项目时，您可以为任何或所有受支持的产品运行模拟器。 对于您未模拟的任何产品，您的应用和代码都将与实时资源（数据库实例、存储桶、函数等）交互。
演示项目	演示 Firebase 项目没有实际 Firebase 配置，也没有实时资源。通常可通过 Codelab 或其他教程来访问这些项目。 演示项目的 ID 带有 demo- 前缀。	使用演示 Firebase 项目时，您的应用和代码仅与模拟器交互。如果您的应用尝试与您没有为其运行模拟器的资源进行交互，该代码将失败。

我们建议您尽可能使用演示项目。演示项目具有以下优势：

• 设置更简单，您无需创建 Firebase 项目也可运行模拟器
• 安全性更强，就算您的代码意外调用了非模拟（生产环境）资源，也不可能发生数据更改、使用资源或产生费用
• 提供更好的离线支持，无需访问互联网即可下载您的 SDK 配置。

注意：如果要模拟跨服务交互（例如由数据库触发的 Cloud Functions 函数或依赖于 Authentication 的规则），您必须确保代码中（initializeApp() 等代码中）的项目 ID 与 Firebase CLI 所使用的项目 ID 相匹配。

对您的应用进行插桩 (instrument) 处理以与模拟器通信

针对 Callable 函数对您的应用进行插桩处理

如果您的原型设计和测试活动涉及 Callable 后端函数，请按如下方式配置与 Cloud Functions for Firebase 模拟器的交互：

Kotlin+KTX

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
MainActivity.kt

Java

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
MainActivity.java

Swift

Functions.functions().useEmulator(withHost: "localhost", port: 5001)
ViewController.swift

Web version 9

详细了解可实现摇树优化的 Web v9 模块化 SDK，并从版本 8 升级。

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "localhost", 5001);
fb_functions_emulator_connect.js

Web version 8

详细了解可实现摇树优化的 Web v9 模块化 SDK，并从版本 8 升级。

firebase.functions().useEmulator("localhost", 5001);
emulator-suite.js

注意：仅限 Android。Android 网络安全配置政策可能会影响您的代码与 Cloud Functions 模拟器交互的方式，因为后者通过未加密的 HTTP 在本地传送数据。从 Android 9（API 级别 28）开始，明文通信默认处于停用状态。您可以设置一个 network_security_config.xml 文件，将 Cloud Functions 模拟器列入白名单，以便在 localhost 上进行开发。请参阅相关 Android 开发者文档。

对您的应用进行插桩处理以便模拟 HTTPS 函数

代码中的每个 HTTPS 函数都将从本地模拟器按以下网址格式提供：

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

例如，采用默认主机端口和区域的简单 helloWorld 函数将在以下位置提供：

https://localhost:5001/$PROJECT/us-central1/helloWorld

对您的应用进行插桩处理以便模拟后台触发的函数

Cloud Functions 模拟器支持以下来源的后台触发函数：

• Realtime Database 模拟器
• Cloud Firestore 模拟器
• Authentication 模拟器
• Pub/Sub 模拟器

如需触发后台事件，您可以使用 Emulator Suite 界面修改后端资源，也可以使用适用于您平台的 SDK 将应用或测试代码连接到模拟器，之后再修改后端资源。

测试用于处理扩展程序发出的自定义事件的处理程序

对于通过 Cloud Functions v2 处理 Firebase Extensions 自定义事件的函数，Cloud Functions 模拟器会与 Eventarc 模拟器配对，以支持 Eventarc 触发器。

如需针对发出事件的扩展程序测试自定义事件处理程序，您必须安装 Cloud Functions 模拟器和 Eventarc 模拟器。

如果 Eventarc 模拟器正在运行，Cloud Functions 运行时会在当前进程中将 EVENTARC_EMULATOR 环境变量设置为 localhost:9299。设置 EVENTARC_EMULATOR 环境变量后，Firebase Admin SDK 会自动连接到 Eventarc 模拟器。您可以按照配置 Local Emulator Suite 中的说明修改默认端口。

正确配置环境变量后，Firebase Admin SDK 会自动向 Eventarc 模拟器发送事件。反过来，Eventarc 模拟器会回调 Cloud Functions 模拟器以触发注册的处理程序。

您可以在 Emulator Suite 界面中查看 Cloud Functions 日志，详细了解处理程序的执行情况。

配置本地测试环境

如果您的函数依赖于基于 dotenv 的环境配置，您可以在本地测试环境中模拟该行为。

使用本地 Cloud Functions 模拟器时，您可以通过设置 .env.local 文件来替换项目的环境变量。.env.local 的内容优先于 .env 和项目特定的 .env 文件。

例如，一个项目可以包含以下三个文件，这些文件中包含的用于开发和本地测试的值会略有不同：

.env	.env.dev	.env.local
PLANET=Earth AUDIENCE=Humans	AUDIENCE=Dev Humans	AUDIENCE=Local Humans

在本地环境中启动时，模拟器会加载环境变量，如下所示：

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Cloud Functions 模拟器中的 Secret 和凭据

Cloud Functions 模拟器支持使用 Secret 存储和访问敏感配置信息。默认情况下，模拟器将尝试使用应用默认凭据访问生产 Secret。在某些情况（例如 CI 环境）下，模拟器可能会由于权限限制而无法访问 Secret 值。

与 Cloud Functions 模拟器对环境变量的支持类似，您可以通过设置 .secret.local 文件来替换 Secret 值。这样，您就可以轻松地在本地测试函数，尤其是当您无法访问 Secret 值时。

还有其他哪些工具可以用来测试 Cloud Functions 函数？

其他原型设计和测试工具可作为对 Cloud Functions 模拟器的补充：

• Cloud Functions Shell，允许对交互式迭代函数进行原型设计和开发。此 shell 采用带有 REPL 样式界面的 Cloud Functions 模拟器进行开发。未提供与 Cloud Firestore 或 Realtime Database 模拟器的集成。借助该 shell，您可以模拟数据并执行函数调用，从而模拟与 Local Emulator Suite 目前不支持的产品（如 Analytics、Remote Config 和 Crashlytics）之间的交互。
• Firebase Test SDK for Cloud Functions，一种使用 Mocha 框架进行函数开发的 Node.js 环境。事实上，Cloud Functions Test SDK 在 Cloud Functions shell 上提供了自动化功能。

如需详细了解 Cloud Functions shell 和 Cloud Functions Test SDK，请参阅以交互方式测试函数和 Cloud Functions 单元测试。

Cloud Functions 模拟器与生产环境的区别

对于大多数使用场景，Cloud Functions 模拟器与生产环境相当接近。我们投入了大量精力来确保节点运行时中的一切尽可能接近生产环境。不过，模拟器不会模拟完整的容器化生产环境。因此，虽然函数代码会按实际方式执行，但环境的其他方面（即本地文件、函数崩溃后的行为等）会有所不同。

Cloud IAM

Firebase Emulator Suite 不会尝试复制或遵从任何与 IAM 相关的运行行为。模拟器遵循提供的 Firebase 安全规则，但在通常会使用 IAM 的情况下（例如，用来设置 Cloud Functions 函数调用服务帐号以及权限等），模拟器不可配置，并且将使用开发者机器上的全局可用帐号（类似于直接运行本地脚本）。

内存和处理器限制

模拟器不会针对函数强制执行内存或处理器限制。不过，模拟器确实会通过 timeoutSeconds 运行时参数支持超时函数。

请注意，在模拟器中运行函数时，函数的执行时间可能与生产环境中的不同。我们建议您在使用模拟器完成函数设计和测试后，在生产环境中运行小规模测试以确认执行时间。

针对本地环境和生产环境的差异制定计划

由于模拟器是在本地机器上运行，因此它依赖本地环境运行应用以及内置程序和实用程序。

请注意，用于 Cloud Functions 函数开发的本地环境可能与 Google 生产环境不同：

• 您在本地安装的、用于模拟生产环境的应用（例如此教程中的 ImageMagick）的行为可能与在生产环境中的行为有所不同，尤其是在您需要其他版本或在非 Linux 环境中进行开发时。不妨将所缺失程序的您自己的二进制文件副本与您的函数一同部署。

• 同样的，内置的实用程序（如 ls、mkdir 等 shell 命令）可能与生产环境中的可用版本不同，尤其是当您在非 Linux 环境（例如 macOS）中进行开发时。如需解决此问题，您可以使用原生命令的纯节点替代方案，或构建 Linux 二进制文件与您的部署捆绑。

重试

Cloud Functions 模拟器不支持在失败后重新执行函数。

后续步骤

• 如需查看一组精选视频和详细的操作方法示例，请点击 Firebase 模拟器培训播放列表。
• 如需详细了解 Cloud Functions for Firebase 模拟器，请参阅在本地运行函数。