您可以在 App Hosting 部署之前使用 App Hosting 模拟器(Firebase Local Emulator Suite 的一部分)对应用执行本地测试。
在使用 App Hosting 模拟器之前,请确保您了解整体 Firebase Local Emulator Suite 工作流,而且已安装和配置 Local Emulator Suite 并查看其 CLI 命令。
本主题假定您已熟悉 App Hosting。如果需要,请查看 App Hosting 简介和其他资料,以帮助您了解 App Hosting 的运作方式。
App Hosting 模拟器的用途
借助 App Hosting 模拟器,您可以在本地测试和优化 Web 应用。这可以简化您的开发流程,并提高使用 Firebase 构建并在 App Hosting 上部署的 Web 应用的质量。
App Hosting 模拟器:
- 让您可以使用
apphosting.yaml
配置文件中定义的环境变量和 Secret 在本地运行 Web 应用。 - 可以使用
apphosting.emulator.yaml
文件替换环境变量和 Secret,以便在模拟器中使用。 - 可与其他 Firebase 模拟器搭配使用。如果您使用的是 Firestore、Auth 或任何其他模拟器,Local Emulator Suite 可确保这些模拟器先于 App Hosting 模拟器启动。
配置模拟器
首先,请按照安装、配置和集成 Local Emulator Suite 中的说明安装并初始化 Local Emulator Suite。除了您要设置的任何其他 Firebase 模拟器之外,请务必选择 App Hosting
Emulator
。CLI 会提示您输入一些 App Hosting 模拟器值,其中包括:
- 相对于项目的应用根目录;如果您将 monorepo 与 App Hosting 搭配使用,这是非常重要的。
- 您是否要替换任何本地开发值。
firebase init emulators
=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ App Hosting Emulator
◯ Firestore Emulator
◯ Database Emulator
◯ Hosting Emulator
◯ Pub/Sub Emulator
◯ Storage Emulator
◯ Eventarc Emulator
(Move up and down to reveal more choices)
? Specify your app's root directory relative to your project (./)
? The App Hosting emulator uses a file called apphosting.emulator.yaml to
override values in apphosting.yaml for local testing. This codebase does not
have one, would you like to create it? (Y/n)
? Which environment variables would you like to override? (Press <space> to
select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ MEMCACHE_ADDR
◯ API_KEY
? What new value would you like for plaintext MEMCACHE_ADDR?
? What would you like to name the secret reference for API_KEY? (test-api-key)
? What new value would you like for secret TESTKEY [input is hidden]? [input is hidden]
? Your config has secret values. Please provide a comma-separated list of users
or groups who should have access to secrets for local development:
✔ Successfully set IAM bindings on secret test-api-key.
您在此设置流程中提供的所有值都将用于更新 firebase.json
中的 App Hosting 模拟器配置。此外,您还可以通过直接更新 firebase.json
来配置 App Hosting 模拟器。App Hosting 模拟器的架构如下:
{
...
"emulators": {
"apphosting": {
"startCommand": <command> [optional]
"rootDirectory": <path> [optional]
}
}
}
- 在模拟器初始化时,系统会自动生成并设置
startCommand
。如果未提供,模拟器将检测并运行您的软件包管理系统的 dev 命令。 rootDirectory
用于支持 monorepo 项目设置。如果您的 Web 应用位于子目录中,则您需要提供该目录相对于根目录(firebase.json
的位置)的路径。
管理模拟
模拟器初始化会在应用的根目录中创建一个 apphosting.emulator.yaml
文件。此配置文件的架构与生产环境中使用的 apphosting.yaml
文件相同,但仅适用于本地开发。默认情况下,模拟器会从 apphosting.yaml
文件读取配置,但如果存在 apphosting.emulator.yaml
文件,则该文件中的配置会被赋予优先级。
apphosting.emulator.yaml
文件的设计可确保安全提交并与同事共享。为确保您不会意外将敏感数据提交到源代码库,在 apphosting.yaml
中是 Secret 的任何环境变量在 apphosting.emulator.yaml
中也必须是 Secret。如果密文在生产环境和本地开发环境之间不需要更改(例如 Gemini API 密钥),则无需将其添加到 apphosting.emulator.yaml
;而是向您的团队授予对该密文的访问权限。
如果您的应用使用许多 Secret(例如,三个不同服务的 API 密钥,每个密钥分别针对生产环境、预演环境和本地开发环境具有不同的值),则可能会超出 Cloud Secret Manager 的免费层级,并且每增加一个 Secret 每月需要支付 0.06 美元。如果您希望在源代码控制系统之外管理本地配置以避免此费用,可以使用旧版 apphosting.local.yaml
文件。与 apphosting.emulator.yaml
不同,此文件允许为 apphosting.yaml
中的 Secret 值环境变量提供明文值。
向用户或群组授予对密文的访问权限
模拟器启动时,系统会读取存储在 apphosting.emulator.yaml
中的 Secret。这意味着您的开发团队需要访问该密钥。您可以使用 apphosting:secrets:grantaccess
命令通过电子邮件向用户或群组授予对密钥的访问权限。
firebase apphosting:secrets:grantaccess test-api-key --emails my-team@my-company.com
在适用的情况下,考虑在 apphosting.emulator.yaml
中使用仅限测试的密钥,这些密钥无权访问生产数据、不能产生全局副作用(发送电子邮件、扣款信用卡),并且/或者配额较低。这有助于确保未经审核的代码对实际造成的影响更小。
建议使用 Google 群组管理对 Secret 的访问权限,而不是向单个用户授予访问权限。这样可以简化向开发者团队引入新成员的流程,因为将他们添加到群组后,他们将获得所需的所有 Secret 的访问权限。您可能已经有一个适当的群组,供开发者相互沟通。通过 Google 群组控制访问权限还有助于确保,当开发者退出您的团队后,他们会在从电子邮件群组中移除后失去对所有 Secret 的访问权限。不过,如果该密钥有权访问生产数据或会产生实际副作用,您可能仍需要使用 firebase apphosting:secrets:set
轮替密钥并为其赋予新值。
运行模拟器
firebase emulators:start
这将启动 firebase.json
文件中定义的包括 App Hosting 模拟器在内的所有模拟器。