企业官网建设流程全解析

Builder.io 可视化开发平台快速指南：10 分钟跑通一个 React 可视化编辑页面

【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder

Builder.io 是一款可视化开发平台：你在浏览器里的可视化编辑器中拖拽组件、编辑页面内容，渲染则由你现有的 React、Vue、Svelte 代码完成。本文用仓库里的 React 示例带你跑通最小闭环，再依次讲组件注册、个性化与上线。需要 Node.js 16+ 和 10 分钟，结束时你会拥有一个能在浏览器里编辑、一键发布的页面。

你也有这些时刻吗

这一节结束时，你会能说清这个问题为什么值得专门做一个工具。

• 改一个按钮文案，要提交代码、等一次部署？
• 设计师的每次修改意见，都要开发再翻译一遍成代码？
• 运营改个内容，你得翻代码找到那串字符串？

这三个问题的根子相同：内容和代码缠在一起。Builder.io 把两者拆开——内容变成结构化数据，在编辑器里可视化编辑；代码留在你手里，只负责渲染。下面先讲清它解决什么，再用 10 分钟跑通最小闭环。

它到底解决什么问题：编辑器与你的代码各在哪

这一节结束时，你能一句话说出 Builder.io 的定位，以及它和传统 CMS 的差别。

它的定位是 Visual Development（可视化开发），支持 React、Vue、Svelte、Qwik 等主流框架，并且是接到你已有项目里的。和传统 CMS 的核心差别在于：它不接管你的前端技术栈，也不另生成一套站点。你在编辑器里拖出来的页面是一份内容数据，运行时由 SDK 取回来，交给你的项目组件渲染——也就是说，编辑器里改的，就是生产代码里跑的，发布链路不变。

工作流程是一个三步循环：

1. 编辑：在可视化编辑器里拖组件、拼页面、改属性
2. 保存：发布后内容以结构化数据入库，带版本历史
3. 渲染：应用运行时按 URL 取内容，交给BuilderComponent渲染

它凭什么值得一试：

• 框架无关：仓库里 React、Vue、Svelte、Angular 都有现成集成示例
• 复用现有组件：你的 React 组件可直接注册，编辑器里用同一套
• 零代码改内容：内容变更不需要重新构建，发布即生效
• 实现全部开源：SDK、CLI、插件都在仓库里，可查证

10 分钟跑通最小闭环

这一节结束时，你能在浏览器里看到自己编辑并发布出来的页面。

1. 克隆仓库并进入示例目录：

git clone https://gitcode.com/GitHub_Trending/bu/builder cd builder/examples/react-js

运行后终端应提示克隆完成、无报错；React 示例里是完整的集成代码。

2. 安装依赖：

npm install

运行后终端应打印 "added xxx packages" 且无错误；网络慢就先换镜像源。

3. 填写账号里的两个值：点击控制台左下角组织图标，新建 Space 时选择 "Add Builder to an existing site or app"，命名 "My React App"；再到页面模型设置里，把 Preview URL 填成http://localhost:5173（务必带上 http://）。

4. 填写入口文件src/main.jsx里的公开 API Key：

import { builder } from '@builder.io/react'; builder.init('YOUR_API_KEY'); // 换成你空间里的 Public API Key

这是唯一要改的一行代码；保存后 SDK 就能从你的空间拉取内容。

5. 启动开发服务器：

npm run dev

运行后终端应打印出http://localhost:5173；在浏览器打开，应看到示例自带的 Home/About 静态页——这是第一个检查点：此时还看不到 Builder 页面是正常的，因为你还没建内容。

6. 创建第一个页面：在控制台新建一条 Page 条目，拖一个标题块和文本块拼成首屏，把 URL 路径设为/home，点击发布。

7. 验证：回浏览器刷新http://localhost:5173/home，应看到刚拼好的页面。✅

小贴士：Preview URL 决定编辑器从哪个地址打开你的站点，换环境时记得同步改这个值。

如何把自己的组件注册进编辑器

这一节结束时，你能让自己的 React 组件出现在编辑器面板里，拖进来就能用。

原理一句话：组件代码留在你的项目里，你只是告诉编辑器"它有哪些输入、什么类型"。看设计系统示例里的 Button 组件，注册写在examples/react-design-system/src/components/Button/Button.builder.js：

import { Builder } from '@builder.io/react'; import { Button } from './Button'; Builder.registerComponent(Button, { name: 'Button', inputs: [ { name: 'text', type: 'string', required: true, defaultValue: 'Click me' }, { name: 'link', type: 'url', required: true, defaultValue: '/foobar' }, ], });

inputs里每一项都会变成编辑器右侧属性面板中的一个字段：string 是输入框，url 是链接字段，还可以用enum变成下拉。注册后记得在入口把该文件 import 一次（参考src/builder-settings.js，就是一排 import）；刷新编辑器后，"Button" 一项就会出现在插入面板里。

接着做四步：

1. 拖拽 Button 进画布
2. 点击它选中
3. 在右侧属性面板把 text 改成 "Buy now"
4. 点击发布，再回浏览器验证按钮由你的组件渲染出来

访问者看到的就是你 React 组件渲染出的按钮，只是 props 不同——这就是"编辑器里改 = 生产代码里变"。

Builder.io 可视化编辑器页面草稿状态预览

设计系统示例里有一整套已注册组件可参考，还能用Builder.register('insertMenu', ...)把组件按分组摆进编辑器的插入菜单。

让页面会"变"：条件、个性化与动态数据

这一节结束时，你能让同一个页面对不同人展示不同内容，并接上外部数据。

先看"变"是怎么实现的。示例里按 URL 取内容（src/main.jsx）：

const content = await builder.get('page', { url: window.location.pathname, }).promise();

路由变化时会按新路径重新请求；未发布的 URL 取不到内容，走 404 分支。也就是说"页面"不是写死在代码里的，而是实时取回的——你在编辑器里改完并发布，下一次请求就不同。

条件展示基于 targeting：在编辑器右侧面板选中某个组件，打开 "Conditions" 选项卡，设置类似"仅移动端显示"的规则；请求时 SDK 会按规则返回对应版本。A/B 测试与个性化容器的流程可看 SDK 文档配图：

动态数据有两条路：

• 接数据源：用内容模型存商品列表之类的结构化数据，页面里循环渲染
• 接外部服务：用插件目录里的现成插件，比如接 plugins/algolia/ 做搜索、在编辑器里配置索引；图片资源交给 plugins/cloudinary/ 处理

性能上可做三件事：只加载当前页面用到的组件；给内容请求降频；长列表改成分页或虚拟滚动。

上线与团队协作：5 行说清

这一节结束时，你能把示例部署到生产域名，并让团队直接预览。

1. 运行npm run build做生产构建，终端应输出构建产物且无错误
2. 运行npx vercel --prod部署，终端给出生产域名后，在浏览器打开验证页面可正常渲染
3. 回 Builder.io 把页面模型的 Preview URL 从http://localhost:5173改为生产域名
4. 在组织设置里分配成员角色：编辑可改不可发，审核人可批准发布
5. 用内容历史功能核对任意条目的修改记录，改坏了从历史里找回旧版本

Builder.io 已发布页面的线上预览效果

出问题先查这 3 处

这一节结束时，你能对三个高频问题做自助排查。

现象：编辑器或页面白屏先查 API Key：src/main.jsx里的YOUR_API_KEY是否换成了公开密钥、是否属于当前空间；再查 Preview URL 和开发服务器地址是否一致（端口 5173、带 http://）；还不行就清缓存或用无痕窗口，排除旧内容。

现象：自定义组件不显示先查控制台有没有注册报错；再核对registerComponent的name和编辑器插入面板里的名字是否一致；最后确认注册文件被入口 import 了——没被打包的组件不会出现。

现象：内容变多后页面慢先查是否取了全部字段（按需只取需要的fields）；再查图片是否走了处理插件；长列表是否一次性全量渲染，改成分页或虚拟滚动。

延伸阅读：仓库 README.md 有完整目录说明，想读实现可从 packages/core/ 入手。

接下来，你可以注册第一个业务组件，或接一个真实数据源。API 细节以官方文档为准，问题可到社区里问；想直接看代码，就从 examples/react-js/ 开始。

【免费下载链接】builderVisual Development for React, Vue, Svelte, Qwik, and more项目地址: https://gitcode.com/GitHub_Trending/bu/builder