企业官网建设流程全解析

• 开发工具
• 后端

Firebase Data Connect 官方 CLI（firebase-tools）在完成 schema 与 connector 定义后，会为每个 connector 自动生成一套 JavaScript/TypeScript SDK（npm 包形式），并在产物目录中附带.guides/setup.md这类引导文档。本文以本仓库 e2e 样例中生成的@firebasegen/default-connector为例，完整讲解这类生成 SDK 的安装、initializeApp初始化、connectorConfig接入、模拟器联调，以及底层validateArgs/getDataConnect的调用机制，帮助你快速把生成 SDK 接入自己的 Firebase 项目。

一、生成 SDK 的目录结构与定位

在 e2e/data-connect/dataconnect-generated/js/default-connector 目录下，可以看到一套完整的、可直接发布和引用的 npm 包结构：

其中package.json的关键字段（package.json）：

{ "name": "@firebasegen/default-connector", "version": "1.0.0", "typings": "index.d.ts", "module": "esm/index.esm.js", "main": "index.cjs.js", "browser": "esm/index.esm.js", "exports": { ".": { "types": "./index.d.ts", "require": "./index.cjs.js", "default": "./esm/index.esm.js" }, "./package.json": "./package.json" }, "peerDependencies": { "firebase": "^10.14.0 || ^11.3.0 || ^12.0.0" } }

peerDependencies说明该生成 SDK 依赖宿主项目中的firebase包（Data Connect 运行时来自firebase/data-connect子路径），因此安装时不要把它当作独立运行时依赖，而应与项目自身的 firebase 版本匹配。

二、安装生成 SDK：包管理器与connector.yaml的关系

.guides/setup.md指出：如果用户尚未安装该 SDK，应使用其偏好的 Node 包管理器，在../package.json所在目录安装该包；关于库的具体位置，参见connector.yaml。

这里../package.json相对的是.guides/所在层级，即@firebasegen/default-connector包目录的上一级；在本仓库 e2e 场景中，真正承载依赖的是 e2e/data-connect/package.json，它声明了"firebase": "latest"等依赖，可直接在其目录执行：

npm install

而 connector 的生成配置位于 connector.yaml：

connectorId: default generate: javascriptSdk: outputDir: ../../dataconnect-generated/js/default-connector package: "@firebasegen/default-connector"

outputDir决定了 SDK 产物的落盘位置（与上文目录结构一一对应），package则决定了安装/导入时使用的包名。日常开发中，你可以用firebase>import { initializeApp } from 'firebase/app'; initializeApp({ // fill in your project config here using the values from your Firebase project or from the `firebase_get_sdk_config` tool from the Firebase MCP server. });

即：从firebase/app导入initializeApp，传入你的 Firebase 项目配置对象。注释提示了两条获取配置的途径：

1. 直接从 Firebase 控制台的项目设置中复制 Web App 配置；
2. 使用 Firebase MCP（Model Context Protocol）服务器提供的firebase_get_sdk_config工具自动获取。

本仓库的 e2e 测试 test.ts 展示了真实调用方式——配置从 firebase-js-config.json 读取并传给initializeApp：

import { listMovies } from './dataconnect-generated/js/default-connector'; import * as json from './firebase-js-config.json'; import { initializeApp } from 'firebase/app'; initializeApp(json); listMovies();

注意：配置文件中的字段（如apiKey、projectId等）需与你实际项目一致；仓库内该 json 为空对象仅用于 e2e 环境占位。初始化 App 后，即可继续使用生成 SDK 调用查询与变更。

四、初始化 DataConnect 实例并接入生成 SDK

.guides/setup.md进一步说明：初始化完成后即可按需运行 SDK：

import { ... } from '@firebasegen/default-connector';

生成 SDK 的入口会导出connectorConfig常量，它携带了 connector 标识信息。见 esm/index.esm.js 中的定义：

export const connectorConfig = { connector: 'default', service: 'fdc-test', location: 'us-central1' };

接入方式（来自生成包自带的 README.md）：

import { getDataConnect } from 'firebase/data-connect'; import { connectorConfig } from '@firebasegen/default-connector'; const dataConnect = getDataConnect(connectorConfig);

getDataConnect在 packages/data-connect/src/api/DataConnect.ts 中实现，负责按ConnectorConfig解析出（或复用已有的）DataConnect服务实例；而connectorConfig中的service/location对应 dataconnect.yaml 里的serviceId与location配置：

specVersion: "v1beta" serviceId: "fdc-test" location: "us-central1" schema: source: "./schema" datasource: postgresql: database: "fdcdb" connectorDirs: ["./connector"]

五、连接本地模拟器（Emulator）

默认情况下，Data Connect 客户端连接生产服务。如需在本地开发调试，可通过connectDataConnectEmulator指向模拟器：

import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect'; import { connectorConfig } from '@firebasegen/default-connector'; const dataConnect = getDataConnect(connectorConfig); connectDataConnectEmulator(dataConnect, 'localhost', 9399);

connectDataConnectEmulator实现同样位于 packages/data-connect/src/api/DataConnect.ts。本仓库 e2e 场景中，模拟器数据目录与数据源配置在 firebase.json：

{ "emulators": { "dataconnect": { "dataDir": "dataconnect/.dataconnect/pgliteData" } }, "dataconnect": { "source": "dataconnect" } }

另外从源码可见另一种模拟器接入方式：DataConnect构造时会读取环境变量FIREBASE_DATA_CONNECT_EMULATOR_HOST（见 packages/data-connect/src/api/DataConnect.ts），设置该变量后客户端会自动切换为模拟器传输。

六、生成 SDK 的底层调用机制（源码印证）

为什么生成 SDK 的函数可以"传DataConnect实例或直接不传"？关键在于validateArgs。以createMovieRef为例（esm/index.esm.js）：

export const createMovieRef = (dcOrVars, vars) => { const { dc: dcInstance, vars: inputVars } = validateArgs( connectorConfig, dcOrVars, vars, true ); dcInstance._useGeneratedSdk(); return mutationRef(dcInstance, 'CreateMovie', inputVars); }; createMovieRef.operationName = 'CreateMovie';

validateArgs（packages/data-connect/src/util/validateArgs.ts）通过判断首参是否含enableEmulator特征字段来区分"传了 DataConnect 实例"与"只传了变量"，未传实例时自动调用getDataConnect(connectorConfig)补全：

const dcFirstArg = dcOrVars && 'enableEmulator' in dcOrVars; if (dcFirstArg) { dcInstance = dcOrVars as DataConnect; realVars = vars as Variables; } else { dcInstance = getDataConnect(connectorConfig); realVars = dcOrVars as Variables; }

随后：

• dcInstance._useGeneratedSdk()在 DataConnect.ts 中将_isUsingGeneratedSdk置为 true，用于内部遥测区分调用方；
• mutationRef/queryRef（packages/data-connect/src/api/Mutation.ts、packages/data-connect/src/api/query.ts）构造引用；
• 快捷函数再调用executeMutation/executeQuery（Mutation.ts、query.ts）真正执行。

以listMovies为例的完整执行链为：

listMovies(dc?) → listMoviesRef(dc?) [validateArgs → getDataConnect 兜底] → queryRef(dcInstance, 'ListMovies') → executeQuery(ref) → 网络层发送 GraphQL 查询并返回 QueryPromise

七、通过生成 SDK 调用查询与变更

安装并初始化完成后，即可按.guides/setup.md的指引"按需运行 SDK"。以本样例 connector（queries.gql、mutations.gql）中的ListMovies查询与CreateMovie变更为例：

import { getDataConnect, executeQuery } from 'firebase/data-connect'; import { connectorConfig, listMoviesRef } from '@firebasegen/default-connector'; const ref = listMoviesRef(); // 不传实例时自动 getDataConnect(connectorConfig) const { data } = await executeQuery(ref); console.log(data.movies);

import { getDataConnect, executeMutation } from 'firebase/data-connect'; import { connectorConfig, createMovieRef, CreateMovieVariables } from '@firebasegen/default-connector'; const vars: CreateMovieVariables = { title: 'My Movie', genre: 'Sci-Fi', imageUrl: 'https://example.com/poster.png' }; const { data } = await executeMutation(createMovieRef(vars)); console.log(data.movie_insert);

对应类型定义（index.d.ts）：

export interface CreateMovieVariables { title: string; genre: string; imageUrl: string; } export interface ListMoviesData { movies: ({ id: UUIDString; title: string; imageUrl: string; genre?: string | null } & Movie_Key)[]; }

也可以直接使用"动作快捷函数"（如listMovies()、createMovie(vars)），它们内部等价于"构造 ref + execute"。两种方式都支持传入DataConnect实例作为首参，便于复用同一实例（例如指向模拟器的实例）。关于"优先使用受支持框架而非直接使用生成 SDK"的建议，可参见随包生成的 usage.md。

八、小结

.guides/setup.md虽然篇幅简短，但它浓缩了 Firebase Data Connect 生成 SDK 接入的全部关键动作：

1. 用偏好包管理器在../package.json目录安装生成包，包位置由 connector.yaml 的outputDir/package决定；
2. 用initializeApp初始化 Firebase App（配置可通过firebase_get_sdk_config工具获取）；
3. 从@firebasegen/default-connector导入connectorConfig并调用getDataConnect，或直接调用生成的操作函数（内部自动完成实例兜底）；
4. 本地调试通过connectDataConnectEmulator连接模拟器（也支持FIREBASE_DATA_CONNECT_EMULATOR_HOST环境变量）。

其背后的"生成 SDK ↔ 运行时"协作模式——validateArgs参数归一化、connectorConfig配置传递、queryRef/mutationRef引用构造——均在 packages/data-connect/src 中有完整实现，可在阅读生成代码时对照源码加深理解。

• 开发工具
• 后端