企业官网建设流程全解析

• 低代码
• 前端
• 后端

导读

本文基于仓库中的 examples/preact-minimal 示例，讲解如何在 Preact（而非 React）环境中以最小化的工程结构集成 Plasmic 视觉构建器。该示例项目演示了完整的接入链路：通过@plasmicapp/loader-react初始化 Loader、用PlasmicRootProvider包裹应用根部、再用PlasmicComponent渲染云端组件，并配合 Vite 与@preact/preset-vite完成构建。读完本文，你将掌握 Preact 应用接入 Plasmic 的最小可行方案，理解 Loader 运行时各组件的职责边界，并能自行替换为自己的 Plasmic 项目 ID 与 Token 落地使用。

示例概览：最小 Preact 应用长什么样

示例目录结构如下（全部关键文件均可直接查看）：

examples/preact-minimal/ ├── src/ │ ├── App.tsx # 组件入口：Loader 初始化 + 渲染 Plasmic 组件 │ └── index.tsx # Preact 渲染入口，挂载到 #root ├── index.html # 页面骨架与模块脚本入口 ├── package.json # 依赖与 npm 脚本 ├── tsconfig.json # TypeScript 编译配置 └── vite.config.ts # Vite 配置，启用 Preact 插件

整个应用的核心代码量极少，App.tsx加index.tsx总共不过三十余行，却完整覆盖了 Plasmic Loader 集成的三要素：初始化 Loader、包裹 Root Provider、渲染目标组件。这正是 "minimal"（最小化）的含义——不引入路由、不引入数据请求框架，只保留让 Plasmic 组件在 Preact 下渲染所需的最小骨架。

初始化 Loader：把 Plasmic 项目接入代码库

依赖清单

先看 package.json 中的依赖构成，它直接决定了集成方式：

"dependencies": { "@plasmicapp/loader-react": "^1.0.180", "preact": "^10.11.1", "preact-render-to-string": "^5.2.5" }, "devDependencies": { "@preact/preset-vite": "^2.4.0", "vite": "^3.0.3", "typescript": "^4.7.4" }

要点说明：

• @plasmicapp/loader-react是 Preact 应用接入 Plasmic 的核心包，它同时负责在浏览器端按需拉取组件代码（headless 加载器模式），并导出自定义组件注册 API；
• preact与preact-render-to-string分别是运行时与 SSR 字符串渲染所需的依赖；
• @preact/preset-vite提供 Vite 的 Preact 语法转换插件，使tsx文件中的 JSX 正确编译为 Preact 的h()调用而非 React 的createElement；
• 脚手架来源于 nano-react-app，随后按 Preact 习惯改写，因此整体工程风格非常轻量。

初始化代码剖析

src/App.tsx 中的初始化代码是整个示例的灵魂：

import { initPlasmicLoader, PlasmicComponent, PlasmicRootProvider, } from "@plasmicapp/loader-react"; const LOADER = initPlasmicLoader({ projects: [ { id: "jzrCyUTP1h82GbByDRVb1L", token: "YF9LaKBauPomd2UMk0M3JMJ2gDWRejTV8N50kYUv9pECVFPUZdelJgYdxE45aenJMZNe4rvbBb73RqbtwmsQ", }, ], });

initPlasmicLoader接收一个配置对象，其中projects数组的每一项包含：

从源码层面看，该函数定义在 packages/loader-react/src/index.ts：

export function initPlasmicLoader(opts: InitOptions): PlasmicComponentLoader { const internal = new InternalPlasmicComponentLoader(opts); return new PlasmicComponentLoader(internal); }

它内部创建了一个InternalPlasmicComponentLoader（其完整配置项定义在 packages/loader-react/src/loader-shared.ts 的InitOptions接口中）。除projects外，InitOptions还支持platform（"react" | "nextjs" | "gatsby"）、preview、apiHost/cdnHost、onClientSideFetch、alwaysFresh、i18n等高级配置。对于 Preact 应用，采用默认platform即可，因为这些选项主要服务于框架特有能力（如 Next.js 的 App Router 场景），并不影响 Preact 下的基本渲染。

Loader 是单例性质的对象：PlasmicComponentLoader内部持有 bundle 缓存（见loader-shared.ts中BaseInternalPlasmicComponentLoader的bundle字段），组件数据按需拉取后即缓存复用，alwaysFresh: true才会强制每次走网络重新获取。因此在模块顶层创建一次、全局复用，是最贴合设计意图的用法。

渲染链路：RootProvider 与 PlasmicComponent

export function App() { return ( <PlasmicRootProvider loader={LOADER}> <PlasmicComponent component="Homepage" componentProps={{ title: "Minimal Preact app" }} /> </PlasmicRootProvider> ); }

PlasmicRootProvider：全局上下文

PlasmicRootProvider负责向整棵组件树提供 Plasmic 运行时上下文，其源码位于 packages/loader-react/src/PlasmicRootProvider.tsx。它的核心职责包括：

• 接收loader实例，作为全局数据源；
• 支持globalVariants（全局变体）、prefetchedData（预取数据）、skipCss/skipFonts、translator、Head/Link注入等可选能力；
• 通过 React Context 将上下文向下传递，供PlasmicComponent消费。

当PlasmicComponent检测到没有现成的PlasmicRootProvider时会直接抛出You must use <PlasmicRootProvider/> at the root of your app的错误（见 PlasmicComponent.tsx），因此 Provider 是渲染 Plasmic 组件的强制前提。

PlasmicComponent：按名称渲染云端组件

PlasmicComponent接收三个关键 props（源码见 PlasmicComponent.tsx）：

• component：要渲染的组件名或页面组件路径，本示例渲染的是名为Homepage的组件；
• projectId：当多个项目存在同名组件时用于消歧（可选）；
• componentProps：向云端组件注入的 props，本示例传入{ title: "Minimal Preact app" }，对应 Plasmic 画布中Homepage组件暴露的title参数。

PlasmicComponent内部通过usePlasmicComponent从 Loader 的组件注册表解析出实际组件，首次渲染时若数据尚未拉取，Loader 会按需向 Plasmic 服务器发起请求并合并 bundle（对应loader-shared.ts中的maybeFetchComponentData/fetchAllData逻辑）。组件解析支持按名称、按页面路径或按{ name, projectId }对象三种查找方式，均为 Loader 的标准能力。

值得一提的是PlasmicRootProvider与PlasmicComponent都来自@plasmicapp/loader-react，而该包的所有导出统一声明在 packages/loader-react/src/index.ts，其中还包括registerComponent、registerFunction、usePlasmicQueryData、extractPlasmicQueryData等后续可扩展的能力，说明这套最小骨架天然可以向上生长为完整的 Preact 集成方案。

挂载与工程配置：从入口到构建

Preact 渲染入口

src/index.tsx 是标准的 Preact 挂载代码：

import { render } from "preact"; import { App } from "./App"; render(<App />, document.getElementById("root")!);

与 React 的createRoot().render()不同，这里直接使用 Preact 自带的render函数将App挂载到#root节点，!非空断言表明该节点必然存在于 HTML 中。

HTML 入口

index.html 提供了页面骨架：

<body style="margin: 0;"> <div id="root"></div> <script type="module" src="./src/index.tsx"></script> </body>

注意script使用了type="module"，这是 Vite 处理 TSX 入口的标准方式——浏览器不直接执行 TSX，而是由 Vite 开发服务器实时编译后以 ES Module 方式提供。margin: 0的内联样式避免 Plasmic 页面内容与浏览器默认边距叠加，保证视觉还原度。

Vite 与 TypeScript 配置

vite.config.ts 是整个构建链的关键：

import preact from "@preact/preset-vite"; import { defineConfig } from "vite"; export default defineConfig({ plugins: [preact()], });

@preact/preset-vite插件完成了 JSX→Preact 的编译转换，这是与 React 项目的根本区别：若缺少该插件，Vite 默认会按 React 的 JSX runtime 编译，产物将无法在 Preact 运行时正常工作。

tsconfig.json 中值得注意的选项：

• "jsx": "preserve"：JSX 交由 Vite 插件处理，TypeScript 只做类型检查而不负责 JSX 转换；
• "baseUrl": "./src"：支持相对src目录的导入；
• "moduleResolution": "Node"、"strict": true、"target": "ES2015"为常规严格配置；
• "include": ["src/**/*"]限定类型检查范围。

运行与验证

package.json 提供了四组可直接使用的脚本：

进入examples/preact-minimal目录后，依次执行yarn install（或npm install）、yarn start即可体验。页面渲染成功后，Homepage组件会以传入的titleprop 展示 "Minimal Preact app" 文案，证明 Loader 已成功拉取并渲染云端组件。

把它改造成你自己的 Preact 项目

把示例迁移到自己的项目只需三步：

1. 替换项目凭据：将initPlasmicLoader中projects数组的id与token替换为你自己的 Plasmic 项目 ID 与 API Token；
2. 调整组件名与 props：把PlasmicComponent的component改为你要渲染的组件名（或在 Plasmic 中定义的页面路径），并按需传入componentProps；
3. 按需扩展：若需要把自定义代码组件接入 Plasmic 画布，可在初始化后调用LOADER.registerComponent(...)，该能力由 Loader 的注册表机制提供（对应loader-shared.ts中registerComponent抽象方法及其实现），并在PlasmicComponent中按组件名引用。

需要注意的限制：@plasmicapp/loader-react的 Loader 模式面向的是"运行时按需拉取组件代码"的 headless 接入方式，因此要求项目保持可联网访问 Plasmic 服务；若需要完全离线的代码生成方案（codegen），则应参考仓库中的custom-targeting-codegen、supabase-auth-nextjs-pages-codegen等示例，它们使用plasmic.json与本地生成代码，与本示例的接入范式不同。

小结

examples/preact-minimal用最少的文件验证了一条完整的接入链路：initPlasmicLoader建立与 Plasmic 项目的连接 →PlasmicRootProvider注入全局上下文 →PlasmicComponent按名称渲染云端组件，再由 Preact 的render挂载到 DOM。配合@preact/preset-vite，一个仅有 5 个源文件的 Preact 工程即可渲染出由 Plasmic 视觉构建器产出的真实页面组件。这套最小骨架既可以直接复用，也可以作为向 Preact 生态（如路由、数据请求、自定义组件注册）扩展的起点，是理解 Plasmic Loader 运行机制的绝佳入门示例。

• 低代码
• 前端
• 后端