企业官网建设流程全解析

Metabase Modular Embedding SDK 快速上手：用 API Key 五分钟在 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 官方 Quickstart 为主干，完整演示如何在自有的 React 应用中使用 Modular embedding SDK 嵌入一个交互式仪表盘：从在 Metabase 管理后台启用 SDK、创建 API Key，到安装@metabase/embedding-sdk-react包、编写最小可运行的嵌入代码。读完本文，你将掌握一套「评估用」的最小嵌入链路，并了解该链路与生产环境 JWT SSO 方案的边界，以及 SDK 包与 Metabase 实例之间基于版本 dist-tag 的匹配机制。

这套快速入门方案的适用边界

在动手之前，先明确这套方案的能力边界。本文的快速入门方案具有以下特征：

• 仅用于评估：它的目的是让你在最短时间内亲眼看到 SDK 的效果；
• 仅限本地开发环境：localhost被自动纳入允许来源（CORS），无需额外配置跨域；
• Metabase 本身不必运行在本地：你的 Metabase 可以部署在远程或 Metabase Cloud 上，SDK 通过你提供的实例 URL 访问它；
• 同时兼容 OSS 与 EE 版本：无论是自托管还是 Metabase Cloud，无论是开源版还是企业版，都可以走这条快速通道。

如果你要将 SDK 用于生产环境，则必须在此基础上继续配置 JWT SSO 认证，这要求 Pro 或 Enterprise 许可。也就是说，本文的 API Key 方案是「先看到效果」，JWT SSO 才是「安全上线」。

前置条件

开始之前，请确认满足以下条件：

• Metabase 版本 52 及以上（OSS 或 EE 均可），安装方式参考安装 Metabase；
• React 版本兼容：根据 Modular embedding SDK 前置要求，需要 React 18 或 React 19、Node.js 20.x 及以上；
• 如果你还没有现成的应用，可以改用带样例应用的快速入门；如果连 Metabase 都还没有，可以先用 Quickstart CLI 一键拉起一个 Docker 版 Metabase。

从 SDK 源码看，SDK 包目录位于 enterprise/frontend/src/embedding-sdk-package，其导出入口定义在 index.ts，属于企业版前端代码仓库的一部分，这解释了为何 SDK 相关能力在企业版仓库中维护。

总览：五步完成嵌入

把仪表盘嵌入你的应用，需要依次完成五步：

1. 在 Metabase 中启用 SDK
2. 在 Metabase 中创建 API Key
3. 在应用中安装 SDK
4. 在应用中嵌入 SDK 组件
5. 查看嵌入的 Metabase 仪表盘

1. 在 Metabase 中启用 SDK

登录 Metabase 后，点击右上角的网格图标，进入Admin > Embedding > Modular，打开SDK for React开关。

官方完整配置入口在 Modular embedding SDK 总览文档 中有更细的说明：在Admin > Embedding页面打开Modular embedding SDK后，还需要在Cross-Origin Resource Sharing (CORS)一栏填写允许嵌入 SDK 的站点来源（多个来源用空格分隔），localhost会被自动包含。本文的本地评估场景因此无需手动添加 CORS 来源。

2. 在 Metabase 中创建 API Key

仍在 Admin 控制台中，进入Settings > Authentication，切换到API keys标签页，创建一个新的 API Key。官方建议按如下方式填写：

• Key name：Modular embedding SDK（便于识别用途即可，非强制）；
• Group：选择Admin（因为这只是本地测试用的凭据）。

创建完成后复制生成的 API Key 字符串，下一步会把它写进前端代码。该 Key 将作为MetabaseProvider的认证凭据，仅在本地方案中使用。

3. 在应用中安装 SDK

安装与你 Metabase 主版本号匹配的@{major}-stabledist-tag。这样做的原因是：npm 包中的 TypeScript 类型与导出的组件，必须与你的 Metabase 实例所提供的 SDK Bundle 保持一致。以 Metabase 60 为例：

使用 npm：

npm install @metabase/embedding-sdk-react@60-stable

使用 Yarn：

yarn add @metabase/embedding-sdk-react@60-stable

版本匹配规则详解

关于版本兼容性，SDK 版本文档 给出了更完整的规则，这里提炼为一张速查表：

架构：SDK 包与 SDK Bundle 的拆分

理解版本匹配规则背后的原因，需要了解 Metabase 57 起 SDK 的两段式架构（详见 introduction.md）：

• SDK Package：@metabase/embedding-sdk-reactnpm 包本身是一个轻量级引导库，主要职责是加载并运行真正的 SDK 代码；
• SDK Bundle：完整的 SDK 实现由你的 Metabase 实例（自托管或 Cloud）直接提供，是 Metabase 的一部分，从而保证 SDK 主代码与其对应实例永远兼容。

从仓库源码可以印证这一点：MetabaseProvider组件内部通过useLoadSdkBundle根据authConfig.metabaseInstanceUrl动态加载 SDK Bundle（见 MetabaseProvider.tsx），运行时代码从window.METABASE_EMBEDDING_SDK_BUNDLE上读取getSdkStore、useInitData等由 Bundle 注入的接口（见同文件 L20-L52）；而 SDK 包还会通过 get-sdk-bundle-script-element.ts 查找页面中由 Bundle 注入的<script>元素。因此「包版本跟随实例版本」是这套架构的正确使用姿势。

4. 在应用中嵌入 SDK 组件

在你的应用中引入 SDK 组件并完成最小配置。以嵌入仪表盘 ID 为 1 的仪表盘为例（新实例上 ID 1 通常是示例仪表盘，也可以换成任意仪表盘 ID）：

import { InteractiveDashboard, MetabaseProvider, defineMetabaseAuthConfig, } from "@metabase/embedding-sdk-react"; /** * 创建传给 MetabaseProvider 的认证配置。 * 请将 metabaseInstanceUrl 与 apiKey 替换为你自己的值。 */ const authConfig = defineMetabaseAuthConfig({ metabaseInstanceUrl: "https://metabase.example.com", apiKey: "YOUR_API_KEY", }); /** * 嵌入你的第一个仪表盘。这里嵌入的是 ID 为 1 的仪表盘。 */ export default function App() { return ( <MetabaseProvider authConfig={authConfig}> <InteractiveDashboard dashboardId={1} /> </MetabaseProvider> ); }

这段示例代码与仓库中的官方片段完全一致，见 docs/embedding/sdk/snippets/quickstart/example.tsx。

关键 API 说明

• MetabaseProvider：SDK 的上下文提供者，负责加载 SDK Bundle、初始化 Redux store 并向子组件注入认证与主题配置。从源码看，它被设计为全局唯一实例：内部通过EnsureSingleInstance强制单实例，若检测到多个MetabaseProvider会给出告警（见 MetabaseProvider.tsx），同时其子组件在ClientSideOnlyWrapper中渲染，这也解释了 SDK 不支持服务端渲染（SSR）的限制。
• defineMetabaseAuthConfig：接收MetabaseAuthConfig并原样返回，本质是一个带类型的配置声明辅助函数（见 define-metabase-auth-config.ts），用于获得完整的类型提示。
• InteractiveDashboard：交互式仪表盘组件，接受dashboardId等属性。SDK 还导出了StaticDashboard（静态展示）、EditableDashboard（可编辑）、InteractiveQuestion/StaticQuestion（问题/图表）、CollectionBrowser（收藏夹浏览）、CreateQuestion、CreateDashboardModal等一系列组件，完整导出清单见 index.ts。

5. 查看嵌入的 Metabase 仪表盘

运行你的应用，访问包含嵌入仪表盘的页面，即可看到渲染结果：

如果页面空白，请按以下顺序排查：

1. 确认 Metabase 侧已启用SDK for React；
2. 确认metabaseInstanceUrl与apiKey已替换为真实值；
3. 确认 npm 包 dist-tag 主版本与 Metabase 主版本一致（见上文版本速查表）；
4. 本地访问时浏览器地址须为localhost，因为 CORS 默认只自动放行本地来源。

生产化之前的下一步

快速验证通过后，继续深入以下方向：

• 外观定制：通过 主题与外观定制 调整组件样式，使嵌入内容与应用视觉无缝衔接；
• 认证与权限：继续在 Metabase 与应用中配置 JWT SSO，实现用户登录、权限管理与生产环境部署——这是从「评估」走向「上线」的必经之路；
• 更多组件：官方还提供了嵌入单个图表、AI 对话、收藏夹浏览器、动作（Actions）以及插件系统等进阶文档。

常见问题与限制

• 每个应用页面只能嵌入一个仪表盘，但可以在同一页面嵌入多个问题（Question），或利用仪表盘标签页在一张仪表盘内组织多套卡片布局；
• SDK 不支持：已验证内容（verified content）、官方收藏夹（official collections）、仪表盘链接卡片（dashboard link cards）以及服务端渲染（SSR），详见 SDK 限制；
• Leaflet 依赖冲突：如果应用依赖 Leaflet 1.x，可能遇到兼容性问题，可尝试升级到 Leaflet 2.x；
• @types/react版本冲突：当 SDK 与应用使用不同主版本的@types/react时，可在package.json中用 npm 的overrides或 Yarn 的resolutions强制统一版本（具体配置示例见 introduction.md）。

没有 Metabase 或没有应用怎么办

本文假设你已同时拥有应用与 Metabase 实例。如果条件不满足，官方提供了两条替代路径：

• 只有应用、没有 Metabase：使用 Quickstart CLI，一条命令npx @metabase/embedding-sdk-react@latest start即可在 Docker 中拉起 Metabase、创建仪表盘并生成可运行的 React 组件；
• 没有应用：克隆官方样例 React 应用（metabase-nodejs-react-sdk-embedding-sample），按{major}-stable分支选择与 Metabase 版本对应的代码，配合 Docker 快速启动或手动走完 JWT 配置全流程。

两条路径的示例代码分别位于 quickstart-cli/example.tsx 与 quickstart-with-sample-app/example.tsx，可对照阅读。

至此，你已经完成了 Modular embedding SDK 的最小闭环：启用 → 建 Key → 装包 → 嵌入 → 查看。下一步的关键决策点只有一个：是否进入生产环境。如果是，请立刻转向 JWT SSO 认证。

【免费下载链接】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