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

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/metabaseMetabase 的 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 需要满足条件要求ReactReact 18 或 React 19Node.jsNode.js 20.x 或更高Metabase版本 1.52 及以上对应 SDK 版本从 52 起关于版本兼容有一个关键规则详见 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 安装 MetabaseDocker 一行命令如果你还没有 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.nioALL-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 安装 SDKnpm / yarn 二选一在你的 React 应用中安装metabase/embedding-sdk-reactnpm install metabase/embedding-sdk-react或使用 yarnyarn add metabase/embedding-sdk-react若你的 Metabase 是 60 版本官方 quickstart 推荐明确指定 dist-tagnpm install metabase/embedding-sdk-react60-stable # 或 yarn add metabase/embedding-sdk-react60-stabletypes/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作为 peerDependenciesmain指向./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 由两部分组成参见 官方架构说明SDK Packagemetabase/embedding-sdk-reactnpm 包一个轻量级引导bootstrapper库主要职责是加载并运行 SDK Bundle 代码同时提供 TypeScript 类型与组件定义SDK Bundle完整的 SDK 运行时代码直接由你的 Metabase 实例自托管或 Metabase Cloud作为 Metabase 的一部分对外提供从而保证 SDK 主代码与对应 Metabase 实例永远兼容。这一设计的优点SDK 的核心逻辑随 Metabase 版本发布与升级宿主应用只需安装轻量的引导包避免了SDK 版本与 Metabase 版本错位的兼容性灾难。源码佐证位于 MetabaseProvider.tsxMetabaseProviderInner通过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-reactlatest start该命令会自动完成以下步骤其实现代码在 enterprise/frontend/src/embedding-sdk-package/cli/ 目录下拆分为一个个steps/前置检查确认你在 React 项目顶层执行、Docker 正在运行若未安装 SDK 会自动安装并写入package.json数据库连接可选询问是否连接你自己的数据库若选择否将使用 Metabase 自带的 Sample Database 生成嵌入仪表盘若选择是则引导填写数据库引擎、host、端口、用户名、密码并让你挑选 13 张表想体验多租户就选含用户 ID 列的表随后对这些表做 X-ray 生成仪表盘Metabase 搭建询问一个管理员邮箱无需真实邮箱仅用于登录刚搭起的实例自动用 Docker 拉起 Metabase、创建管理员账号并生成 API Key权限与多租户可选需 Pro/EE 许可证可指定用于行级安全的列Metabase 会基于该列的值设置行级权限参见 行级与列级安全并生成一个 mock Express 服务器默认保存到./mock-server需另开终端npm run start用于签发 JWT生成示例 React 组件默认写入./src/components/metabase包括AnalyticsDashboard——嵌入仪表盘的仪表盘组件AnalyticsPage——带 Provider 包装的仪表盘页面真实应用中MetabaseProvider应放在应用根组件ThemeSwitcher——明暗主题切换UserSwitcher——假用户切换AnalyticsProvider/EmbeddingProvider——示例状态与主题、认证配置包装。完成后把AnalyticsPage /加入你的页面启动应用即可看到嵌入式仪表盘工具搭建的 Metabase 运行在http://localhost:3366登录凭据保存在METABASE_LOGIN.json。体验完毕可删除这些示例文件自行配置主题与用户体系。六、生产级认证从 API Key 到 JWT SSOREADME 的 quickstart 仅覆盖本地体验官方 quickstart 明确强调生产环境必须配置 JWT SSO且需要 Pro 或 Enterprise 计划。API Key 方式仅限本地评估示例见 auth-config-api-key.tsxconst 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.tsxconst 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 通信从而实现用户身份透传、权限管控与会话管理。更多细节见 认证文档。七、组件矩阵一张表看懂该选哪个组件组件用途典型场景MetabaseProvider全局 Provider加载 SDK、初始化 store、注入主题与认证应用根组件StaticQuestion只读问题/图表展示固定图表InteractiveQuestion可交互的查询构建器让用户自助查询StaticDashboard只读仪表盘嵌入式报表页面InteractiveDashboard可交互仪表盘过滤、钻取数据分析页EditableDashboard可在宿主应用中编辑的仪表盘内部数据工作台CollectionBrowser集合浏览器让用户浏览内容CreateQuestion新建问题入口用户自助建查询CreateDashboardModal新建仪表盘弹窗内容创建流程MetabotQuestionAI 问答Metabot自然语言问数各组件还有配套 hooksuseAction执行 Action、useCurrentUser获取当前 SDK 用户、useCreateDashboardApi编程式创建仪表盘、useMetabot等。更完整的使用说明分别见 嵌入图表、嵌入仪表盘、嵌入集合浏览器、嵌入 AI 聊天、Actions 与 自定义可视化。八、主题定制、加载状态与插件系统外观定制通过defineMetabaseTheme定义MetabaseTheme可定制颜色、字体等让嵌入组件与宿主应用视觉统一详见 外观文档 与 配置文档。加载/错误/空状态SDK 允许自定义加载器与错误组件SdkErrorComponent等详见 loading-and-errors。插件系统可通过plugins配置扩展仪表盘卡片菜单、点击行为click actions等参考 plugins 文档。Next.js 支持SDK 不支持 SSR官方提供了 Next.jsApp 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_EDITIONee 运行 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_URLhttp://localhost:3010 bun run storybook-embedding-sdk10.2 测试组件 e2e 测试位于e2e/test-component/scenarios/embedding-sdk/以 Cypress component tests 运行需设置MB_EDITIONee及若干企业版 token先构建 SDK 再执行CYPRESS_TESTING_TYPEcomponent bun run test-cypressSample App 兼容性测试针对每个 Sample App 拉取、启动并运行 Cypress 测试本地运行示例SDK_TEST_SUITEmetabase-nodejs-react-sdk-embedding-sample-e2e bun run test-cypress-host-sample-appsHost App 集成测试用于验证 SDK 与不同框架/打包器的宿主应用集成如类型冲突等棘手场景Host App 放在仓库的 e2e/embedding-sdk-host-apps/ 下如vite-6-host-app、next-15-app-router-host-app等示例ENTERPRISE_TOKENtoken SDK_TEST_SUITEvite-6-host-app-e2e HOST_APP_ENVIRONMENTproduction 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 的落地路径可以归纳为三条主线环境Docker/JAR 拉起 EE 版 Metabase → 管理后台启用 Modular embedding SDK 并配置 CORS → 按{major}-stabledist-tag 安装metabase/embedding-sdk-react嵌入以MetabaseProvider为根按需组合InteractiveDashboard、StaticQuestion、InteractiveQuestion等组件并通过defineMetabaseTheme与插件系统完成外观和交互定制生产化将认证从 API Key 升级为 JWT SSOfetchRequestToken结合权限与多租户设置即可把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考