企业官网建设流程全解析

Metabase Embedded Analytics SDK 实战指南：用 React 组件化嵌入图表、仪表盘与查询构建器

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 的 Embedded analytics SDK（模块化嵌入 SDK）允许你在自己的 React 应用中直接嵌入独立的 Metabase 组件——包括单个图表、仪表盘、查询构建器（Query Builder）、AI 问答等，并且可以按组件精细管控访问权限与交互能力，配合深度主题定制实现与宿主应用无缝融合的界面。本文以仓库内 enterprise/frontend/src/embedding-sdk-package/README.md 为主线，结合该目录下的 SDK 源码与 docs/embedding/sdk/ 系列官方文档，完整讲解环境准备、SDK 安装、组件嵌入、认证配置、架构原理与开发调试，读完即可在自己的 React 应用中跑通第一个嵌入式仪表盘。

一、SDK 是什么：把 Metabase 拆成可嵌入的 React 组件

Embedded analytics SDK 的核心价值在于"组件化嵌入"。与传统的 iframe 整页嵌入不同，SDK 让你以 React 组件的方式将 Metabase 的单个能力"摆放"进自己的页面：

• 独立图表：单个 question（问题）的图表视图；
• 仪表盘：只读的静态仪表盘、可交互的仪表盘、甚至可在宿主应用内直接编辑的仪表盘；
• 查询构建器：把 Metabase 的查询构建器嵌入到你的应用中，让用户在你的产品里自助建查询；
• 更多能力：集合浏览器（Collection Browser）、新建问题、新建仪表盘弹窗、AI 问答（Metabot）等。

从 SDK 包入口文件 可以看到 SDK 对外公开的组件全家桶：

export { CollectionBrowser } from "./components/public/CollectionBrowser"; export { CreateQuestion } from "./components/public/CreateQuestion"; export { CreateDashboardModal } from "./components/public/CreateDashboardModal"; export { EditableDashboard } from "./components/public/dashboard/EditableDashboard"; export { InteractiveDashboard } from "./components/public/dashboard/InteractiveDashboard"; export { StaticDashboard } from "./components/public/dashboard/StaticDashboard"; export { InteractiveQuestion } from "./components/public/InteractiveQuestion"; export { StaticQuestion } from "./components/public/StaticQuestion"; export { MetabaseProvider } from "./components/public/MetabaseProvider"; export { MetabotQuestion } from "./components/public/MetabotQuestion";

同时导出useAction、useCurrentUser、useCreateDashboardApi、useMetabot等 hooks，以及defineMetabaseAuthConfig、defineMetabaseTheme等配置辅助函数，全部组件实现位于enterprise/frontend/src/embedding-sdk-package/components/public/目录下。

二、前置条件与版本兼容性

根据 SDK 官方文档 的"Modular embedding SDK prerequisites"一节，使用 SDK 需要满足：

关于版本兼容有一个关键规则（详见 SDK 版本说明）：

• Metabase 56 及更早版本：SDK 包的 major 版本必须与你的 Metabase major 版本一致；
• Metabase 57 及之后：可以不指定 dist-tag，直接安装最新已发布的 SDK major 版本。

推荐的安装方式始终是使用与 Metabase major 匹配的@{major}-stabledist-tag（见下文"安装 SDK"），确保 npm 包导出的 TypeScript 类型与组件，和 Metabase 实例提供的 SDK Bundle 保持同步。

三、Quickstart：从零跑通第一个嵌入式仪表盘

README 给出了完整的快速上手路径，分三步：安装 Metabase、安装 SDK、嵌入组件。

3.1 安装 Metabase：Docker 一行命令

如果你还没有 Metabase 实例，README 推荐了最快捷的 Docker 方式（企业版镜像，SDK 属于 EE 功能）：

docker run -d -p 3000:3000 --name metabase metabase/metabase-enterprise:latest

也可以下载 Enterprise 版 JAR 包后直接运行：

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

默认情况下 Metabase 会运行在http://localhost:3000。启动后按 安装文档 完成初始化设置。生产环境使用 SDK 时，需要为企业版激活许可证，参见 激活企业版。

3.2 在 Metabase 中启用 SDK

进入 Metabase 管理后台Admin > Embedding，打开Modular embedding SDK开关；随后在Cross-Origin Resource Sharing (CORS)一栏填入允许嵌入 SDK 的站点 origin（以空格分隔），localhost默认自动包含。

3.3 安装 SDK：npm / yarn 二选一

在你的 React 应用中安装@metabase/embedding-sdk-react：

npm install @metabase/embedding-sdk-react

或使用 yarn：

yarn add @metabase/embedding-sdk-react

若你的 Metabase 是 60 版本，官方 quickstart 推荐明确指定 dist-tag：

npm install @metabase/embedding-sdk-react@60-stable # 或 yarn add @metabase/embedding-sdk-react@60-stable

@types/react版本冲突：在极少数情况下，SDK 与应用可能使用不同 major 版本的@types/react导致 TypeScript 冲突。官方建议在package.json中通过 npm 的overrides或 yarn 的resolutions统一指定一个版本，例如：

// npm { "overrides": { "@types/react": "..." } }

// yarn { "resolutions": { "@types/react": "..." } }

从仓库内的 package.template.json 可以看出该 npm 包的结构：它以react >=18 <=19和react-dom >=18 <=19作为 peerDependencies，main指向./dist/main.bundle.js，并额外导出./nextjs、./data-app、./data-app-dev等子路径，且内置./dist/cli.js作为bin（即 CLI quickstart 入口）。

3.4 嵌入第一个仪表盘组件

以官方 quickstart 示例 为骨架，最小可运行示例为：

import { InteractiveDashboard, MetabaseProvider, defineMetabaseAuthConfig, } from "@metabase/embedding-sdk-react"; // 将 metabaseInstanceUrl 与 apiKey 替换为你的真实值 const authConfig = defineMetabaseAuthConfig({ metabaseInstanceUrl: "https://metabase.example.com", apiKey: "YOUR_API_KEY", }); export default function App() { return ( <MetabaseProvider authConfig={authConfig}> <InteractiveDashboard dashboardId={1} /> </MetabaseProvider> ); }

其中：

• defineMetabaseAuthConfig负责声明认证配置（此处使用 API Key 方式，仅用于本地评估）；
• MetabaseProvider是全局 Provider，负责加载 SDK、初始化 Redux store 并注入主题，通常放在应用根组件；
• InteractiveDashboard是交互式仪表盘组件，dashboardId={1}指向 Metabase 中的仪表盘 ID（新实例中 ID 1 通常是示例仪表盘）。

注意：API Key 方式仅适用于本地评估，不能用于生产。生产环境必须改用 JWT SSO（见下文第六节）。

四、架构原理：SDK Package 与 SDK Bundle 的双层设计

从 Metabase 57 起，SDK 由两部分组成（参见 官方架构说明）：

1. SDK Package（@metabase/embedding-sdk-reactnpm 包）：一个轻量级引导（bootstrapper）库，主要职责是加载并运行 SDK Bundle 代码，同时提供 TypeScript 类型与组件定义；
2. SDK Bundle：完整的 SDK 运行时代码，直接由你的 Metabase 实例（自托管或 Metabase Cloud）作为 Metabase 的一部分对外提供，从而保证 SDK 主代码与对应 Metabase 实例永远兼容。

这一设计的优点：SDK 的核心逻辑随 Metabase 版本发布与升级，宿主应用只需安装轻量的引导包，避免了"SDK 版本与 Metabase 版本错位"的兼容性灾难。

源码佐证位于 MetabaseProvider.tsx：MetabaseProviderInner通过useLoadSdkBundle(props.authConfig.metabaseInstanceUrl, ...)按实例 URL 加载 SDK Bundle，并借助getWindow()?.METABASE_EMBEDDING_SDK_BUNDLE?.getSdkStore?.()获取由 Bundle 创建的 Redux store；在 Bundle 未加载完成（SdkLoadingState.Initialized之前）时组件返回null，加载完成后才渲染子组件。同时该组件用EnsureSingleInstance保证同一时刻只渲染一个MetabaseProvider实例，并用ClientSideOnlyWrapper处理 SSR 场景。

五、CLI Quickstart：一条命令自动完成全套环境搭建

如果你还没有 Metabase 实例，也不想手动配置，官方提供了 CLI 工具（见 quickstart-cli 文档）。在你的 React 应用根目录执行：

npx @metabase/embedding-sdk-react@latest start

该命令会自动完成以下步骤（其实现代码在 enterprise/frontend/src/embedding-sdk-package/cli/ 目录下，拆分为一个个steps/）：

1. 前置检查：确认你在 React 项目顶层执行、Docker 正在运行；若未安装 SDK 会自动安装并写入package.json；
2. 数据库连接（可选）：询问是否连接你自己的数据库；若选择否，将使用 Metabase 自带的 Sample Database 生成嵌入仪表盘；若选择是，则引导填写数据库引擎、host、端口、用户名、密码，并让你挑选 1～3 张表（想体验多租户就选含用户 ID 列的表），随后对这些表做 X-ray 生成仪表盘；
3. Metabase 搭建：询问一个管理员邮箱（无需真实邮箱，仅用于登录刚搭起的实例），自动用 Docker 拉起 Metabase、创建管理员账号并生成 API Key；
4. 权限与多租户（可选，需 Pro/EE 许可证）：可指定用于行级安全的列，Metabase 会基于该列的值设置行级权限（参见 行级与列级安全），并生成一个 mock Express 服务器（默认保存到./mock-server，需另开终端npm run start）用于签发 JWT；
5. 生成示例 React 组件：默认写入./src/components/metabase，包括：
   • AnalyticsDashboard——嵌入仪表盘的仪表盘组件；
   • AnalyticsPage——带 Provider 包装的仪表盘页面（真实应用中MetabaseProvider应放在应用根组件）；
   • ThemeSwitcher——明暗主题切换；
   • UserSwitcher——假用户切换；
   • AnalyticsProvider/EmbeddingProvider——示例状态与主题、认证配置包装。

完成后把<AnalyticsPage />加入你的页面，启动应用即可看到嵌入式仪表盘；工具搭建的 Metabase 运行在http://localhost:3366，登录凭据保存在METABASE_LOGIN.json。体验完毕可删除这些示例文件，自行配置主题与用户体系。

六、生产级认证：从 API Key 到 JWT SSO

README 的 quickstart 仅覆盖本地体验，官方 quickstart 明确强调：生产环境必须配置 JWT SSO，且需要 Pro 或 Enterprise 计划。

API Key 方式（仅限本地评估）示例见 auth-config-api-key.tsx：

const authConfigApiKey = defineMetabaseAuthConfig({ metabaseInstanceUrl: "https://metabase.example.com", apiKey: "YOUR_API_KEY", });

在 Metabase 管理后台Admin > Settings > Authentication > API keys创建 API Key（详见 API keys 文档），评估阶段可选择 Admin 组。

JWT 方式（生产环境），示例见 auth-config-jwt.tsx：

const authConfig = defineMetabaseAuthConfig({ fetchRequestToken: async () => { const response = await fetch( "https://{{ YOUR_CLIENT_HOST }}/api/metabase/auth", { method: "GET", headers: { Authorization: `Bearer ${yourToken}` }, }, ); // 后端应返回形如 { jwt: string } 的 JSON return await response.json(); }, metabaseInstanceUrl: "http://localhost:3000", });

fetchRequestToken从你的后端换取 JWT，再由 SDK 携带该 JWT 与 Metabase 通信，从而实现用户身份透传、权限管控与会话管理。更多细节见 认证文档。

七、组件矩阵：一张表看懂该选哪个组件

各组件还有配套 hooks：useAction（执行 Action）、useCurrentUser（获取当前 SDK 用户）、useCreateDashboardApi（编程式创建仪表盘）、useMetabot等。更完整的使用说明分别见 嵌入图表、嵌入仪表盘、嵌入集合浏览器、嵌入 AI 聊天、Actions 与 自定义可视化。

八、主题定制、加载状态与插件系统

• 外观定制：通过defineMetabaseTheme定义MetabaseTheme，可定制颜色、字体等，让嵌入组件与宿主应用视觉统一；详见 外观文档 与 配置文档。
• 加载/错误/空状态：SDK 允许自定义加载器与错误组件（SdkErrorComponent等），详见 loading-and-errors。
• 插件系统：可通过plugins配置扩展仪表盘卡片菜单、点击行为（click actions）等，参考 plugins 文档。
• Next.js 支持：SDK 不支持 SSR，官方提供了 Next.js（App Router / Pages Router）的认证 API 路由示例，见 Next.js 说明。

九、SDK 的已知限制

根据 官方文档的 SDK limitations，以下内容不受支持：

• Verified content（已验证内容）
• Official collections（官方收藏）
• Dashboard link cards（仪表盘链接卡片）
• 服务端渲染（SSR）

其他限制包括：

• 每个应用页面只能有一个仪表盘；但可在同一页面嵌入多个 question，或使用仪表盘标签页（dashboard tabs）在一个仪表盘内组织多种卡片布局；
• 若应用依赖 Leaflet 1.x 可能遇到兼容性问题，可尝试使用 Leaflet 2.x。

十、本地开发与调试：构建 SDK、Storybook 与测试

如果你打算参与 SDK 开发或本地调试，dev.md 提供了完整指引。需要注意：SDK 包目录内的代码对外部依赖引用有严格约束（专门的 eslint 规则no-external-references-for-sdk-package-code定义在enterprise/frontend/src/.eslintrc.js），目的是保持 SDK 包体积尽可能小。

10.1 构建与 Storybook

# 构建 SDK npm 包 bun run build-embedding-sdk-package # SDK Bundle 随核心应用前端构建，开发时需以 MB_EDITION=ee 运行 build-hot # 若设置了 SKIP_EMBEDDING_SDK，需先取消该环境变量

Storybook 用于带热重载地调试 SDK 组件，需要先在localhost:3000运行一个配置好的实例：在 JWT 认证页启用 User Provisioning 并设置固定 JWT secret；在/admin/embedding/modular启用 "SDK for React"。随后启动：

bun run storybook-embedding-sdk # 指向其他实例： STORYBOOK_METABASE_INSTANCE_URL=http://localhost:3010 bun run storybook-embedding-sdk

10.2 测试

• 组件 e2e 测试：位于e2e/test-component/scenarios/embedding-sdk/，以 Cypress component tests 运行，需设置MB_EDITION=ee及若干企业版 token，先构建 SDK 再执行CYPRESS_TESTING_TYPE="component" bun run test-cypress；
• Sample App 兼容性测试：针对每个 Sample App 拉取、启动并运行 Cypress 测试，本地运行示例：SDK_TEST_SUITE=metabase-nodejs-react-sdk-embedding-sample-e2e bun run test-cypress-host-sample-apps；
• Host App 集成测试：用于验证 SDK 与不同框架/打包器的宿主应用集成（如类型冲突等棘手场景），Host App 放在仓库的 e2e/embedding-sdk-host-apps/ 下（如vite-6-host-app、next-15-app-router-host-app等），示例：ENTERPRISE_TOKEN=<token> SDK_TEST_SUITE=vite-6-host-app-e2e HOST_APP_ENVIRONMENT=production bun run test-cypress-host-sample-apps。这些测试在 CI 上的失败不会阻塞 PR 合并，但通常意味着存在构建错误或破坏兼容性的改动，需针对受影响的 Sample App/Host App 单独提交兼容性修复 PR。

10.3 在本地项目中使用本地构建的 SDK

# 假设 metabase 仓库与你的项目目录同级 yarn add file:../metabase/resources/embedding-sdk # 或 npm 方式（--install-links 会拷贝而非软链接） npm install --install-links ../metabase/resources/embedding-sdk

常见坑位：

• 缓存问题：安装后需清理打包器缓存——next 清.next、vite 清node_modules/.vite、webpack 清node_modules/.cache，推荐每次安装 SDK 后清理；
• Cannot read properties of null (reading 'useRef')：通常是项目中出现多个 React 版本（多因 SDK 以软链接安装、monorepo 或嵌套 node 项目导致 node 解析到不同的react）。若用 npm 安装，改用--install-links创建包副本通常可解决。

十一、总结：从快速体验到生产落地的完整路径

Metabase Embedded analytics SDK 的落地路径可以归纳为三条主线：

1. 环境：Docker/JAR 拉起 EE 版 Metabase → 管理后台启用 Modular embedding SDK 并配置 CORS → 按@{major}-stabledist-tag 安装@metabase/embedding-sdk-react；
2. 嵌入：以MetabaseProvider为根，按需组合InteractiveDashboard、StaticQuestion、InteractiveQuestion等组件，并通过defineMetabaseTheme与插件系统完成外观和交互定制；
3. 生产化：将认证从 API Key 升级为 JWT SSO（fetchRequestToken），结合权限与多租户设置，即可把 Metabase 的分析能力以组件粒度嵌入到自有产品中，同时保持 SDK 与 Metabase 实例的版本天然同步。

相关资源可在仓库内继续深入：SDK 全部源码位于 enterprise/frontend/src/embedding-sdk-package/，SDK 官方文档位于 docs/embedding/sdk/，升级与版本兼容策略见 version.md 与 upgrade.md。

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase