Builder.io Vue SDK 与 Nuxt 3 集成实战从 Visual Editor 到生产部署的完整指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本指南以仓库中的 examples/vue/nuxt-3/README.md 为骨架结合 packages/sdks/output/vue 的 Vue SDK 源码与其 Nuxt 模块实现系统讲解如何在 Nuxt 3 应用中接入 Builder.io包括环境配置、内容获取fetchOneEntry、可视化编辑isPreviewing、自定义组件注册以及开发、构建与生产部署的完整流程。读完本文你将能够独立把一个 Nuxt 3 项目改造为支持 Builder.io 可视化开发的前端应用。Builder.io 是一个可视化开发平台允许非技术人员在页面上直接拖拽组件、编辑内容开发者则通过 SDK 将内容以组件形式渲染到自己的前端应用。本仓库builder提供了面向 React、Vue、Svelte、Qwik 等框架的新一代 SDK由 Mitosis 生成其中builder.io/sdk-vue即针对 Vue 3 / Nuxt 3 的官方 SDK。examples/vue/nuxt-3目录下即包含一个最小可运行的 Nuxt 3 集成示例本文围绕它展开。一、项目概览示例仓库结构examples/vue/nuxt-3是一个基于 Nuxt 3nuxt: ^3.15.3的最小示例工程其文件结构如下examples/vue/nuxt-3/ ├── components/ │ └── HelloWorld.vue # 注册到 Builder 的自定义组件 ├── public/ │ └── favicon.ico ├── app.vue # 应用入口渲染 Builder Content 的页面 ├── nuxt.config.ts # 引入 builder.io/sdk-vue/nuxt 模块 ├── package.json # 依赖与脚本 ├── tsconfig.json ├── package-lock.json核心依赖在 package.json 中定义{ scripts: { build: nuxt build, dev: nuxt dev, generate: nuxt generate, preview: nuxt preview, postinstall: nuxt prepare }, devDependencies: { nuxt: ^3.15.3 }, dependencies: { builder.io/sdk-vue: ^1.0.14 } }值得说明的是示例工程通过 npm 依赖安装builder.io/sdk-vue使用该 SDK 的完整源码位于仓库的 packages/sdks/output/vue当前版本 5.2.11其中 nuxt.js 就是提供给 Nuxt 使用的模块入口。二、Builder.io 平台侧配置在写代码之前先在 Builder.io 平台上完成以下准备对应原文档的 Builder.io Setup 一节登录 builder.io 账户进入账户页面复制你的Public API Key打开 Builder.io Visual Editor可视化编辑器并选择名为page的 model内容模型在编辑器右上角的 URL 输入框中填入http://localhost:3000即可把本地开发服务器作为实时预览目标在编辑器的 Layers图层面板中拖入任意组件刷新后的编辑器就会实时显示该组件——也就是可视化开发的核心体验。原文档还提供了一段 Loom 视频演示最初为 React-Native 录制但操作步骤完全一致。整个流程的本质是Builder.io 平台托管内容数据你的 Nuxt 应用通过 API Key 拉取数据并渲染而 Visual Editor 通过 URL 指向本地开发服务器实现所见即所得。三、Nuxt 3 工程接入 SDK配置 nuxt.config安装依赖后npm install/yarn install/pnpm install均可需要在nuxt.config.ts中注册 SDK 的 Nuxt 模块// https://nuxt.com/docs/api/configuration/nuxt-config export default defineNuxtConfig({ modules: [builder.io/sdk-vue/nuxt], });示例工程中的 nuxt.config.ts 正是如此。这里注册的builder.io/sdk-vue/nuxt指向 SDK 包中的 nuxt.js这是一个基于nuxt/kit的官方模块其实现做了两件事自动注入样式nuxt.options.css.push(builder.io/sdk-vue/css)将 Builder 渲染所需的编译后 CSS 加入 Nuxt 全局 CSS 数组默认开启可通过includeCompiledCss: false关闭。这样你无需像纯 Vue 3 SSR 项目那样手动import builder.io/sdk-vue/css参见 SDK README 的 CSS 一节。服务端运行时初始化可选当initializeNodeRuntime: true时模块会把builder.io/sdk-vue/node/init加入 Vite 的optimizeDeps.exclude并注入一个 server 模式的插件nuxt-isolated-vm-plugin.js。关于第二点背后的原因源码注释写得很清楚SDK 依赖isolated-vm在 Node 服务端安全执行代码的原生模块而 Vite 在 dev server 首次构建时会尝试优化该依赖这既没必要又会报错因此需要排除。同时isolated-vm只在 Node 环境使用浏览器端不应加载。如果你的应用不需要服务端执行 Builder 内容逻辑保持默认initializeNodeRuntime为false即可。关于 Apple SiliconM1/M2的提示SDK 文档packages/sdks/README.md额外提示在 Node v20 M1 Mac 上isolated-vm存在兼容性问题需为运行服务器的命令加上NODE_OPTIONS--no-node-snapshot否则 SDK 会跳过使用isolated-vm。若你恰好是这类环境在启动命令前设置该环境变量即可。四、渲染 Builder 内容app.vue 实战解析示例的 app.vue 完整展示了获取内容 渲染 可视化预览三个环节是整篇文档的核心代码逐段拆解如下。1. 导入 SDK 核心 APIimport { Content, fetchOneEntry, isPreviewing } from builder.io/sdk-vue;Content渲染 Builder 内容的 Vue 组件需与 model 名配合fetchOneEntry根据条件抓取一条 Builder 内容isPreviewing判断当前 URL 是否处于 Builder 可视化预览状态。从源码看fetchOneEntry定义于 packages/sdks/src/functions/get-content/index.ts它会在内部调用fetchEntries({ ...options, limit: 1 })并返回结果数组的第一项同时支持locale参数若传入则会同步设置到userAttributes.locale用于内容本地化。而isPreviewing定义于 packages/sdks/src/functions/is-previewing.ts其实现是检查当前 URL 的 search 参数中是否包含builder.preview在浏览器端使用window.location.search在服务端 SSR 时必须显式传入search参数否则返回false。2. 配置 API Key// TODO: enter your public API key const BUILDER_PUBLIC_API_KEY f1a790f8c3204b3b8c5c1795aeac4660; // ggignore把第二步在 Builder.io 账户页复制的 Public API Key 填入此处示例中是占位 key。注意Public API Key 本身面向公开读取可以出现在前端代码中。3. 在服务端/构建期抓取内容const route useRoute(); // fetch builder content data const { data: content } await useAsyncData(builderData-page-${route.path}, () fetchOneEntry({ model: page, apiKey: BUILDER_PUBLIC_API_KEY, userAttributes: { urlPath: route.path, }, }) );这里使用 Nuxt 3 的useAsyncData包裹fetchOneEntrymodel: page指定读取 Builder.io 中名为page的 model 内容apiKey指定内容密钥userAttributes.urlPath传入当前路由路径让 Builder 按 URL 匹配对应内容这正对应 Builder.io 中 page model 按 URL 定位内容的机制用route.path作为缓存 key 的一部分保证不同页面路径各自缓存内容避免数据串页。由于useAsyncData在 SSR 与客户端水合阶段共享数据这一写法能让 Builder 内容在服务端完成抓取既利于首屏渲染速度也利于 SEO。4. 渲染与预览态处理div v-ifcontent || isPreviewing() div page title: {{ content?.data?.title || Unpublished }} /div Content modelpage :contentcontent :api-keyBUILDER_PUBLIC_API_KEY :customComponentsREGISTERED_COMPONENTS / /div div v-elseContent not Found/div关键点在v-ifcontent || isPreviewing()当页面处于 Builder 可视化预览模式URL 带builder.preview参数时即使当前尚无已发布内容也要渲染Content组件让编辑器中的草稿内容得以展示——这就是未发布也能在编辑器中实时看到的实现原理。content?.data?.title读取 Builder 内容数据中的title字段未发布时显示Unpublished占位若内容不存在且非预览态则显示Content not Found。Content组件接收model、content、api-key以及customComponents自定义组件注册表把 Builder 中的可视化内容翻译为真实的 Vue 组件树。5. 注册自定义组件import HelloWorldComponent from ./components/HelloWorld.vue; // Register your Builder components const REGISTERED_COMPONENTS [ { component: HelloWorldComponent, name: MyFunComponent, canHaveChildren: true, inputs: [ { name: text, type: string, defaultValue: World, }, ], }, ];这是将你自己的 Vue 组件暴露给 Builder 编辑器的方式componentVue 组件本身这里是 HelloWorld.vuename在 Builder 编辑器中显示/拖拽的名称canHaveChildren: true允许在该组件内放置子组件组件模板中定义了slot/slot与之呼应inputs声明组件可配置的 props 输入示例中text为字符串类型默认值World编辑器会自动为其生成可视化配置表单。对应的 HelloWorld.vue 是一个带textprop 和默认 slot 的简单组件template div classhello-world div classtextHello {{ text }}!/div slot/slot /div /template script export default { props: { text: { type: String, default: world, }, }, }; /script这样非技术用户便可在 Builder 编辑器中拖入MyFunComponent并在线调整text文案无需触碰代码。五、开发服务器完成上述配置后启动本地开发服务器默认地址 http://localhost:3000npm run dev此时结合第二节的平台配置访问http://localhost:3000即为 Builder 可视化编辑器的实时预览目标在编辑器 Layers 面板拖入组件页面会实时呈现。六、生产构建与预览构建生产版本npm run build本地预览生产构建产物npm run preview需要说明的是builder.io/sdk-vue的包导出见 packages/sdks/output/vue/package.json同时提供了node服务端渲染、browser浏览器端与edge边缘运行时适用于 workerd、deno、bun、netlify、edge-light 等三套构建产物因此该集成方案在 Nuxt 的 SSR、静态站点生成npm run generate乃至边缘部署场景下均可工作。更多部署方式可参考 Nuxt 官方部署文档针对 Node 服务器、静态托管、Serverless 平台等不同目标。七、SDK 能力与进阶方向能力状态Vue SDK 的功能实现进度可在 packages/sdks/README.md#feature-implementation 的特性表中查询含可用特性、各框架可用 Blocks、Widgets 对照。版本支持builder.io/sdk-vue支持独立的 Vue 3 应用也支持 Nuxt 3见 SDK README 的 Version Support 一节。更多示例仓库中还有配套示例可对照学习例如 examples/vue/vue-3、使用 catch-all 路由的 examples/vue/nuxt-3-catchall通过NuxtPage让每个路由都自动渲染对应 Builder 内容以及基于旧版 SDK 的 examples/vue/nuxt-2-old-sdk。源码阅读入口想深入原理可阅读 SDK 的 Mitosis 源码 packages/sdks/src/functions/get-content/index.ts内容抓取、packages/sdks/src/functions/is-previewing.ts预览态判断以及 Nuxt 模块实现 packages/sdks/output/vue/nuxt.js。八、常见问题与排查思路现象排查方向页面一直显示Content not Found确认 API Key 正确、model 名确为page、当前 URL 路径在 Builder 中已创建对应内容编辑器拖入组件后本地页面无变化确认编辑器 URL 已指向http://localhost:3000且v-if条件包含isPreviewing()自定义组件在编辑器中不可见检查是否已加入customComponentsREGISTERED_COMPONENTS并正确声明inputsdev server 首启报isolated-vm相关错误这是 Vite 优化原生依赖导致可确认模块已注册M1 Node v20 场景参考第三节的环境变量方案SSR 时isPreviewing()恒为 false该函数在服务端需显式传入 search 参数这是源码明确的设计约束结语通过本文你已掌握在 Nuxt 3 中接入 Builder.io 的完整链路平台侧配置 model 与 API Key → 安装builder.io/sdk-vue并注册 Nuxt 模块 → 在app.vue中用fetchOneEntryuseAsyncData抓取内容 → 用Content渲染、用isPreviewing支撑可视化编辑 → 注册自定义组件 → 最后完成 dev / build / preview 的日常开发闭环。这套模式既适合快速搭建可视化营销页也能作为企业级内容中台的渲染层后续可按需扩展 model、接入userAttributes做个性化或参考 catch-all 路由示例实现全站动态渲染。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Builder.io Vue SDK 与 Nuxt 3 集成实战：从 Visual Editor 到生产部署的完整指南
Builder.io Vue SDK 与 Nuxt 3 集成实战从 Visual Editor 到生产部署的完整指南【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder本指南以仓库中的 examples/vue/nuxt-3/README.md 为骨架结合 packages/sdks/output/vue 的 Vue SDK 源码与其 Nuxt 模块实现系统讲解如何在 Nuxt 3 应用中接入 Builder.io包括环境配置、内容获取fetchOneEntry、可视化编辑isPreviewing、自定义组件注册以及开发、构建与生产部署的完整流程。读完本文你将能够独立把一个 Nuxt 3 项目改造为支持 Builder.io 可视化开发的前端应用。Builder.io 是一个可视化开发平台允许非技术人员在页面上直接拖拽组件、编辑内容开发者则通过 SDK 将内容以组件形式渲染到自己的前端应用。本仓库builder提供了面向 React、Vue、Svelte、Qwik 等框架的新一代 SDK由 Mitosis 生成其中builder.io/sdk-vue即针对 Vue 3 / Nuxt 3 的官方 SDK。examples/vue/nuxt-3目录下即包含一个最小可运行的 Nuxt 3 集成示例本文围绕它展开。一、项目概览示例仓库结构examples/vue/nuxt-3是一个基于 Nuxt 3nuxt: ^3.15.3的最小示例工程其文件结构如下examples/vue/nuxt-3/ ├── components/ │ └── HelloWorld.vue # 注册到 Builder 的自定义组件 ├── public/ │ └── favicon.ico ├── app.vue # 应用入口渲染 Builder Content 的页面 ├── nuxt.config.ts # 引入 builder.io/sdk-vue/nuxt 模块 ├── package.json # 依赖与脚本 ├── tsconfig.json ├── package-lock.json核心依赖在 package.json 中定义{ scripts: { build: nuxt build, dev: nuxt dev, generate: nuxt generate, preview: nuxt preview, postinstall: nuxt prepare }, devDependencies: { nuxt: ^3.15.3 }, dependencies: { builder.io/sdk-vue: ^1.0.14 } }值得说明的是示例工程通过 npm 依赖安装builder.io/sdk-vue使用该 SDK 的完整源码位于仓库的 packages/sdks/output/vue当前版本 5.2.11其中 nuxt.js 就是提供给 Nuxt 使用的模块入口。二、Builder.io 平台侧配置在写代码之前先在 Builder.io 平台上完成以下准备对应原文档的 Builder.io Setup 一节登录 builder.io 账户进入账户页面复制你的Public API Key打开 Builder.io Visual Editor可视化编辑器并选择名为page的 model内容模型在编辑器右上角的 URL 输入框中填入http://localhost:3000即可把本地开发服务器作为实时预览目标在编辑器的 Layers图层面板中拖入任意组件刷新后的编辑器就会实时显示该组件——也就是可视化开发的核心体验。原文档还提供了一段 Loom 视频演示最初为 React-Native 录制但操作步骤完全一致。整个流程的本质是Builder.io 平台托管内容数据你的 Nuxt 应用通过 API Key 拉取数据并渲染而 Visual Editor 通过 URL 指向本地开发服务器实现所见即所得。三、Nuxt 3 工程接入 SDK配置 nuxt.config安装依赖后npm install/yarn install/pnpm install均可需要在nuxt.config.ts中注册 SDK 的 Nuxt 模块// https://nuxt.com/docs/api/configuration/nuxt-config export default defineNuxtConfig({ modules: [builder.io/sdk-vue/nuxt], });示例工程中的 nuxt.config.ts 正是如此。这里注册的builder.io/sdk-vue/nuxt指向 SDK 包中的 nuxt.js这是一个基于nuxt/kit的官方模块其实现做了两件事自动注入样式nuxt.options.css.push(builder.io/sdk-vue/css)将 Builder 渲染所需的编译后 CSS 加入 Nuxt 全局 CSS 数组默认开启可通过includeCompiledCss: false关闭。这样你无需像纯 Vue 3 SSR 项目那样手动import builder.io/sdk-vue/css参见 SDK README 的 CSS 一节。服务端运行时初始化可选当initializeNodeRuntime: true时模块会把builder.io/sdk-vue/node/init加入 Vite 的optimizeDeps.exclude并注入一个 server 模式的插件nuxt-isolated-vm-plugin.js。关于第二点背后的原因源码注释写得很清楚SDK 依赖isolated-vm在 Node 服务端安全执行代码的原生模块而 Vite 在 dev server 首次构建时会尝试优化该依赖这既没必要又会报错因此需要排除。同时isolated-vm只在 Node 环境使用浏览器端不应加载。如果你的应用不需要服务端执行 Builder 内容逻辑保持默认initializeNodeRuntime为false即可。关于 Apple SiliconM1/M2的提示SDK 文档packages/sdks/README.md额外提示在 Node v20 M1 Mac 上isolated-vm存在兼容性问题需为运行服务器的命令加上NODE_OPTIONS--no-node-snapshot否则 SDK 会跳过使用isolated-vm。若你恰好是这类环境在启动命令前设置该环境变量即可。四、渲染 Builder 内容app.vue 实战解析示例的 app.vue 完整展示了获取内容 渲染 可视化预览三个环节是整篇文档的核心代码逐段拆解如下。1. 导入 SDK 核心 APIimport { Content, fetchOneEntry, isPreviewing } from builder.io/sdk-vue;Content渲染 Builder 内容的 Vue 组件需与 model 名配合fetchOneEntry根据条件抓取一条 Builder 内容isPreviewing判断当前 URL 是否处于 Builder 可视化预览状态。从源码看fetchOneEntry定义于 packages/sdks/src/functions/get-content/index.ts它会在内部调用fetchEntries({ ...options, limit: 1 })并返回结果数组的第一项同时支持locale参数若传入则会同步设置到userAttributes.locale用于内容本地化。而isPreviewing定义于 packages/sdks/src/functions/is-previewing.ts其实现是检查当前 URL 的 search 参数中是否包含builder.preview在浏览器端使用window.location.search在服务端 SSR 时必须显式传入search参数否则返回false。2. 配置 API Key// TODO: enter your public API key const BUILDER_PUBLIC_API_KEY f1a790f8c3204b3b8c5c1795aeac4660; // ggignore把第二步在 Builder.io 账户页复制的 Public API Key 填入此处示例中是占位 key。注意Public API Key 本身面向公开读取可以出现在前端代码中。3. 在服务端/构建期抓取内容const route useRoute(); // fetch builder content data const { data: content } await useAsyncData(builderData-page-${route.path}, () fetchOneEntry({ model: page, apiKey: BUILDER_PUBLIC_API_KEY, userAttributes: { urlPath: route.path, }, }) );这里使用 Nuxt 3 的useAsyncData包裹fetchOneEntrymodel: page指定读取 Builder.io 中名为page的 model 内容apiKey指定内容密钥userAttributes.urlPath传入当前路由路径让 Builder 按 URL 匹配对应内容这正对应 Builder.io 中 page model 按 URL 定位内容的机制用route.path作为缓存 key 的一部分保证不同页面路径各自缓存内容避免数据串页。由于useAsyncData在 SSR 与客户端水合阶段共享数据这一写法能让 Builder 内容在服务端完成抓取既利于首屏渲染速度也利于 SEO。4. 渲染与预览态处理div v-ifcontent || isPreviewing() div page title: {{ content?.data?.title || Unpublished }} /div Content modelpage :contentcontent :api-keyBUILDER_PUBLIC_API_KEY :customComponentsREGISTERED_COMPONENTS / /div div v-elseContent not Found/div关键点在v-ifcontent || isPreviewing()当页面处于 Builder 可视化预览模式URL 带builder.preview参数时即使当前尚无已发布内容也要渲染Content组件让编辑器中的草稿内容得以展示——这就是未发布也能在编辑器中实时看到的实现原理。content?.data?.title读取 Builder 内容数据中的title字段未发布时显示Unpublished占位若内容不存在且非预览态则显示Content not Found。Content组件接收model、content、api-key以及customComponents自定义组件注册表把 Builder 中的可视化内容翻译为真实的 Vue 组件树。5. 注册自定义组件import HelloWorldComponent from ./components/HelloWorld.vue; // Register your Builder components const REGISTERED_COMPONENTS [ { component: HelloWorldComponent, name: MyFunComponent, canHaveChildren: true, inputs: [ { name: text, type: string, defaultValue: World, }, ], }, ];这是将你自己的 Vue 组件暴露给 Builder 编辑器的方式componentVue 组件本身这里是 HelloWorld.vuename在 Builder 编辑器中显示/拖拽的名称canHaveChildren: true允许在该组件内放置子组件组件模板中定义了slot/slot与之呼应inputs声明组件可配置的 props 输入示例中text为字符串类型默认值World编辑器会自动为其生成可视化配置表单。对应的 HelloWorld.vue 是一个带textprop 和默认 slot 的简单组件template div classhello-world div classtextHello {{ text }}!/div slot/slot /div /template script export default { props: { text: { type: String, default: world, }, }, }; /script这样非技术用户便可在 Builder 编辑器中拖入MyFunComponent并在线调整text文案无需触碰代码。五、开发服务器完成上述配置后启动本地开发服务器默认地址 http://localhost:3000npm run dev此时结合第二节的平台配置访问http://localhost:3000即为 Builder 可视化编辑器的实时预览目标在编辑器 Layers 面板拖入组件页面会实时呈现。六、生产构建与预览构建生产版本npm run build本地预览生产构建产物npm run preview需要说明的是builder.io/sdk-vue的包导出见 packages/sdks/output/vue/package.json同时提供了node服务端渲染、browser浏览器端与edge边缘运行时适用于 workerd、deno、bun、netlify、edge-light 等三套构建产物因此该集成方案在 Nuxt 的 SSR、静态站点生成npm run generate乃至边缘部署场景下均可工作。更多部署方式可参考 Nuxt 官方部署文档针对 Node 服务器、静态托管、Serverless 平台等不同目标。七、SDK 能力与进阶方向能力状态Vue SDK 的功能实现进度可在 packages/sdks/README.md#feature-implementation 的特性表中查询含可用特性、各框架可用 Blocks、Widgets 对照。版本支持builder.io/sdk-vue支持独立的 Vue 3 应用也支持 Nuxt 3见 SDK README 的 Version Support 一节。更多示例仓库中还有配套示例可对照学习例如 examples/vue/vue-3、使用 catch-all 路由的 examples/vue/nuxt-3-catchall通过NuxtPage让每个路由都自动渲染对应 Builder 内容以及基于旧版 SDK 的 examples/vue/nuxt-2-old-sdk。源码阅读入口想深入原理可阅读 SDK 的 Mitosis 源码 packages/sdks/src/functions/get-content/index.ts内容抓取、packages/sdks/src/functions/is-previewing.ts预览态判断以及 Nuxt 模块实现 packages/sdks/output/vue/nuxt.js。八、常见问题与排查思路现象排查方向页面一直显示Content not Found确认 API Key 正确、model 名确为page、当前 URL 路径在 Builder 中已创建对应内容编辑器拖入组件后本地页面无变化确认编辑器 URL 已指向http://localhost:3000且v-if条件包含isPreviewing()自定义组件在编辑器中不可见检查是否已加入customComponentsREGISTERED_COMPONENTS并正确声明inputsdev server 首启报isolated-vm相关错误这是 Vite 优化原生依赖导致可确认模块已注册M1 Node v20 场景参考第三节的环境变量方案SSR 时isPreviewing()恒为 false该函数在服务端需显式传入 search 参数这是源码明确的设计约束结语通过本文你已掌握在 Nuxt 3 中接入 Builder.io 的完整链路平台侧配置 model 与 API Key → 安装builder.io/sdk-vue并注册 Nuxt 模块 → 在app.vue中用fetchOneEntryuseAsyncData抓取内容 → 用Content渲染、用isPreviewing支撑可视化编辑 → 注册自定义组件 → 最后完成 dev / build / preview 的日常开发闭环。这套模式既适合快速搭建可视化营销页也能作为企业级内容中台的渲染层后续可按需扩展 model、接入userAttributes做个性化或参考 catch-all 路由示例实现全站动态渲染。【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考