自定义 Firebase Studio 工作区

借助 Firebase Studio,您可以通过定义一个 .idx/dev.nix 配置文件,根据项目的独特需求定制工作区,该文件描述了以下内容:

  • 您需要运行的系统工具(例如,从终端运行的编译器或其他二进制文件)。
  • 您需要安装的扩展程序(例如,编程语言支持)。
  • 您的应用预览应如何显示(例如,运行 Web 服务器的命令)。
  • 在工作区中运行的本地服务器可用的全局环境变量

如需查看完整功能说明,请参阅 dev.nix 参考文档

通过向项目添加 .idx/mcp.json 文件,您还可以连接到 Model Context Protocol (MCP) 服务器,包括 Firebase MCP 服务器

Nix 和 Firebase Studio

Firebase Studio 使用 Nix 为每个工作区定义环境配置。具体而言,Firebase Studio 使用:

  • Nix 编程语言,用于描述工作区环境。Nix 是一种函数式编程语言。您可以在 dev.nix 文件中定义的属性和软件包库遵循 Nix 属性集语法

  • Nix 软件包管理系统,用于管理工作区可用的系统工具。这类似于特定于操作系统的软件包管理系统,例如 APT (aptapt-get)、Homebrew (brew) 和 dpkg

由于 Nix 环境具备可重现性和声明性,这意味着在 Firebase Studio 中,您可以将 Nix 配置文件作为 Git 代码库的一部分共享,以确保所有项目成员使用相同的环境配置。

基本示例

以下示例展示了用于启用预览的基本环境配置:

{ pkgs, ... }: {

  # Which nixpkgs channel to use.
  channel = "stable-23.11"; # or "unstable"

  # Use https://search.nixos.org/packages to find packages
  packages = [
    pkgs.nodejs_20
  ];

  # Sets environment variables in the workspace
  env = {
    SOME_ENV_VAR = "hello";
  };

  # Search for the extensions you want on https://open-vsx.org/ and use "publisher.id"
  idx.extensions = [
    "angular.ng-template"
  ];

  # Enable previews and customize configuration
  idx.previews = {
    enable = true;
    previews = {
      web = {
        command = [
          "npm"
          "run"
          "start"
          "--"
          "--port"
          "$PORT"
          "--host"
          "0.0.0.0"
          "--disable-host-check"
        ];
        manager = "web";
        # Optionally, specify a directory that contains your web app
        # cwd = "app/client";
      };
    };
  };
}

添加系统工具

如需向工作区添加系统工具(例如编译器或云服务 CLI 程序),请 在 Nix 软件包注册表中查找唯一的软件包 ID,并将其以“pkgs.”为前缀添加到 dev.nix 文件的 packages 对象中。

{ pkgs, ... }: {
  # Which nixpkgs channel to use.
  channel = "stable-23.11"; # or "unstable"

  # Use https://search.nixos.org/packages to find packages
  packages = [
    pkgs.nodejs_20
  ];
  ...
}

这与您通常使用操作系统专用软件包管理系统(例如 APT [aptapt-get]、Homebrew [brew] 和 dpkg)安装系统软件包的方式不同。通过声明性描述所需的系统软件包,可以使 Firebase Studio 工作区更易于共享和重现。

使用本地节点二进制文件

与本地安装的节点软件包相关的二进制文件(例如,在 package.json 中定义的软件包)就像在本地机器上一样,可以通过在终端面板中使用 npx 命令调用它们来执行。

为了进一步提高便利性,如果您位于包含 node_modules 文件夹的目录(例如 Web 项目的根目录),则可以直接调用本地安装的二进制文件,而无需使用 npx 前缀。

添加 gcloud 组件

适用于 Google Cloudgcloud CLI 的默认配置可供所有 Firebase Studio 工作区使用。

如果您需要其他组件,可以将其添加到 dev.nix 文件中:

{ pkgs }: {
  packages = [
    ...
    (pkgs.google-cloud-sdk.withExtraComponents [
      pkgs.google-cloud-sdk.components.cloud-datastore-emulator
    ])
    ...
  ];
}

添加 IDE 扩展程序

您可以通过 OpenVSX 扩展程序注册表,在 Firebase Studio 中通过以下两种方式安装扩展程序:

  • 使用 Firebase Studio 中的扩展程序面板来查找并安装扩展程序。此方法最适合用户专属扩展程序,例如:

    • 自定义颜色主题
    • 编辑器模拟,例如 VSCodeVim
  • 将扩展程序添加到 dev.nix 文件中。共享工作区配置时,这些扩展程序会自动安装。此方法最适合项目专用扩展程序,例如:

    • 编程语言扩展程序,包括特定于语言的调试程序
    • 项目中使用的云服务的官方扩展程序
    • 代码格式化工具

对于后一种方法,您可以通过查找完全限定的扩展程序 ID(采用 <publisher>.<id> 的形式)并将其添加到 idx.extensions 对象中,在 dev.nix 文件中添加 IDE 扩展程序,如下所示:

{ pkgs, ... }: {
  ...
  # Search for the extensions you want on https://open-vsx.org/ and use the format
  # "<publisher>.<id>"
  idx.extensions = [
    "angular.ng-template"
  ];
  ...
}

添加常用服务

Firebase Studio 还为开发过程中可能需要的常用服务提供了简化的设置和配置,包括:

  • 容器
    • Docker (services.docker.*)
  • 消息传递
    • Pub/Sub 模拟器 (services.pubsub.*)
  • 数据库
    • MySQL (services.mysql.*)
    • Postgres (services.postgres.*)
    • Redis (services.redis.*)
    • Spanner (services.spanner.*)

如需详细了解如何在工作区启用这些服务,请参阅 dev.nix 参考文档中的 services.* 部分。

自定义预览

如需详细了解如何自定义应用预览,请参阅预览应用

设置工作区图标

您可以将名为 icon.png 的 PNG 文件放在与 dev.nix 文件同级的 .idx 目录中,以设置工作区自定义图标。然后,Firebase Studio 将在信息中心中使用此图标来表示您的工作区。

由于此文件可以签入到源代码控制系统(例如 Git),这样可以确保所有项目成员在使用 Firebase Studio 时看到相同的项目图标。由于该文件在各个 Git 分支中可能有所不同,因此您可以使用此图标直观地区分 Beta 版应用工作区和正式版应用工作区,以及将此图标用于其他用途。

将自定义设置转换为模板

如需将您的环境配置转变为可供任何人用于创建新项目的“起始环境”,请参阅创建自定义模板的文档。

探索所有自定义选项

如需详细了解环境配置架构,请参阅 dev.nix 参考文档

下载文件

如需将文件打包为 zip 文件下载,请执行以下操作:

  • 在“探索器”窗格中右键点击任意目录,然后选择压缩并下载

如需下载项目目录中的全部内容,请执行以下操作:

  1. 选择文件 > 打开文件夹

  2. 接受默认的 /home/user 目录。

  3. 文件加载完成后,右键点击工作目录,然后选择压缩并下载。如果您使用 App Prototyping agent,工作目录将是 studio。如果使用模板或上传的项目,工作目录名称将是您的项目名称。

  4. 当系统提示您重新构建环境时,点击取消

  5. 下载完成后,从文件菜单重新打开工作目录,以返回工作区。

使用 MCP 服务器

MCP 服务器提供额外的工具和数据源供 Gemini 使用。例如,您可以添加 Firebase MCP 服务器,以便在构建或调试应用时,使用自然语言在 Cloud Firestore 中探索数据。

前提条件

  • 如果 MCP 服务器需要,请确保您已安装正常运行的 Node.js 和 npm。

选择兼容的 MCP 服务器

Firebase Studio 提供对 MCP 服务器的基础支持,这意味着并非所有 MCP 服务器都兼容。选择要添加到 Firebase Studio 工作区的 MCP 服务器时,请注意:

  • 受支持:
    • 标准输入/输出 (stdio) 或不需要特殊身份验证形式的服务器发送事件 (SSE)/可流式传输的 HTTP 传输服务器
    • MCP 服务器提供的工具
  • 目前不受支持:
    • 需要图形界面或桌面会话的服务器
    • MCP 服务器提供的提示、采样或其他资源

添加 MCP 服务器

  1. 在“探索器”(Ctrl+Shift+E) 中,右键点击 .idx 文件夹,然后选择新建文件。将文件命名为 mcp.json,然后按 Enter 键。

  2. 将服务器配置添加到 .idx/mcp.json 文件的内容中。例如,如要添加 Firebase MCP 服务器,请输入:

    {
      "mcpServers": {
       "firebase": {
         "command": "npx",
         "args": [
           "-y",
           "firebase-tools@latest",
           "experimental:mcp"
          ]
        }
      }
    }
    

    此配置文件会告诉 Gemini 要使用哪个 MCP 服务器。在此示例中,我们添加了一个名为 firebase 的服务器,它将使用 npx 命令来安装和运行 firebase-tools@latest。其他 MCP 服务器需要不同的配置,但遵循相同的常规格式

  3. 在终端 (Shift+Ctrl+C) 中,运行完成安装所需的任何命令。例如,如要使用 Firebase MCP 服务器,请输入以下命令登录您的账号:

    firebase login --no-localhost
    

    按照终端中的说明授权会话。某些工具需要关联的 Firebase 项目。您可以使用 Firebase MCP 服务器创建项目,也可以运行以下命令来初始化 Firebase 项目:

    firebase init
    

    这会在您的根目录中创建一个 firebase.json 文件。

  4. 重新构建工作区以完成设置:

    1. 打开命令面板 (Shift+Ctrl+P)。

    2. 输入 Firebase Studio: Rebuild Environment

使用 MCP 工具

安装要使用的 MCP 服务器后,其提供的工具或数据可在以下位置找到:

  • Gemini CLI
  • Gemini in Firebase 对话,使用代理模式和代理(自动运行)模式时
  • App Prototyping agent

例如,如果您添加了 Firebase MCP 服务器,可以要求 Gemini 获取当前项目的 SDK 配置、检索存储在 Cloud FirestoreRealtime Database 中的数据、帮助您设置 Firebase 服务等等

排查 MCP 服务器问题

如果 MCP 服务器无法按预期运行,请打开 Gemini 日志检查是否存在错误:

  1. 在输出 (Shift+Ctrl+U) 中,点击下拉菜单,然后选择 Gemini

  2. 检查以 [MCPManager] 标记开头的消息。这些日志包含有关已设置的 MCP 服务器的信息,以及所有错误消息。您可以使用此信息来排查配置问题。当 MCP 服务器成功连接后,您会看到其添加的工具列表。

如果 MCP 服务器无法安装或连接,请尝试重建工作区:

  1. 打开命令面板 (Shift+Ctrl+P)。

  2. 输入 Firebase Studio: Rebuild Environment

  3. 等待工作区重建完毕,然后再次尝试使用所选的 MCP 服务器。

如果 MCP 服务器已连接,但 Gemini 未使用其提供的工具:

  • 发起新的 Gemini 对话

  • 如果 Gemini 可以在不使用 MCP 工具的情况下完成任务,它可能会尝试其他方法。如果您想使用特定工具,请尝试在提示中指定该工具。例如,您可以这样说“Use firebase_get_sdk_config to get the SDK config for the current project.”

  • 加入 Google Developer Program

后续步骤