Luban H5 本地开发环境搭建与预览渲染引擎构建全指南

原创2026-10-08 23:17:531,345 阅读
文章标签:低代码前端后端

Luban H5 本地开发环境搭建与预览渲染引擎构建全指南

本指南基于 Luban H5 官方文档 docs/en/getting-started/quick-start.md 编写,系统讲解从零搭建 Luban H5 前后端本地开发环境、管理后台权限配置,以及“渲染引擎”(preview engine)的构建原理与源码级实现。读完本文,你将能够独立完成后端 Strapi API 与前端 Vue 编辑器的启动、解决开发中最常见的 403 与预览空白问题,并理解作品 JSON 是如何被渲染引擎转换成手机端 H5 页面的。

概述:先了解 Luban H5 的技术架构

在动手执行命令之前,先花一分钟认识 Luban H5 当前版本的技术栈,这对后续排查问题至关重要:

  • Vue.js:前端框架,负责可视化编辑器与作品渲染引擎(位于 front-end/h5);
  • Strapi.js:开源的 Node.js Headless CMS,为后端提供可定制 API(位于 back-end/h5-api);
  • SQLite:默认数据库,无需额外安装数据库服务。

后端 package.json 中声明的 Node 版本约束为 >=10.16.0 <=14.x.x,因此建议使用 Node LTS(v10 或 v12)进行开发,这一点在中英文文档中均有明确提示。

快速上手:两条命令启动前后端

如果你已经熟悉 Node 与 Yarn(且已安装),直接按照下面的命令即可快速启动:

# 后端
cd back-end/h5-api && yarn && yarn dev

# 前端
# 新开一个终端,回到项目根目录
cd front-end/h5 && yarn && yarn build:engine && yarn dev

若你对该技术栈不熟悉,请继续阅读下面的详细教程,每一步都会展开说明。

搭建后端环境

快速启动

默认情况下,当前路径为 Luban H5 项目的根目录,执行:

cd back-end/h5-api
# 注意:使用 yarn 安装依赖,⚠️ 不要使用 npm
yarn install # 安装依赖

yarn dev # 启动开发服务
# 补充说明:如需在 VSCode 中调试,请使用 npm run localdev

# 默认数据库为 sqlite3,位置在 h5-api/.tmp/data.db

# 访问 http://localhost:1337/admin 管理后台
# 请继续阅读,进行相关配置

几点需要特别说明:

  1. 为何必须用 yarn 而非 npm 安装依赖? 这与项目依赖的解析方式相关(详见原文档引用的 issue 讨论),如果你使用 npm 遇到安装或启动异常,请切换回 yarn 重新安装。
  2. 本地调试命令:文档提到在 VSCode 中调试可运行 yarn localdev,它通过调试端口启动 Strapi 服务,方便打断点跟踪后端代码。
  3. 数据库位置:默认使用 SQLite,数据库文件生成在 back-end/h5-api/.tmp/data.db。这一配置在 config/database.js 中可以找到证据:
module.exports = ({ env }) => ({
  defaultConnection: 'default',
  connections: {
    default: {
      connector: 'bookshelf',
      settings: {
        client: 'sqlite',
        filename: env('DATABASE_FILENAME', '.tmp/data.db'),
      },
      options: {
        useNullAsDefault: true,
      },
    },
  },
});

env('DATABASE_FILENAME', '.tmp/data.db') 意味着你可以通过环境变量 DATABASE_FILENAME 覆盖数据库文件路径;同时该配置文件使用了 Strapi 3 的 Bookshelf 连接器,相关依赖(knex、sqlite3、strapi-connector-bookshelf 等)都已在 back-end/h5-api/package.json 中声明。

管理后台:注册账号与配置权限

启动后端后,在浏览器访问 http://localhost:1337/admin 即可进入 Luban H5 的管理后台(即 Strapi Admin)。管理后台主要承担以下职责:

  • 管理数据库 Model(内容类型);
  • 配置接口权限;
  • 用户注册与管理;
  • 上传素材管理;
  • 接口文档查看。

首次使用步骤:按页面提示注册管理员账号 → 使用该账号登录 → 如需中文界面,可在右上角将语言切换为 zh-Hans(简体中文)。

常见问题一:接口返回 403 Forbidden

本地开发时,如果后端接口报 403 Forbidden,原因通常是接口权限未开放给 Public 角色。解决步骤如下:

  1. 访问 http://localhost:1337/admin;
  2. 进入 Roles And Permission → Public → Permissions;
  3. 为需要公开访问的接口勾选对应权限,使其可被匿名访问。

其中有一项权限是专门**用于上传作品封面图(upload work cover)**的,也需要一并开启,否则编辑器上传封面时会失败。

常见问题二:预览弹窗显示空白

如果预览弹窗中的页面显示空白,大概率是没有构建预览所需的渲染引擎,解决方案请直接跳转下方“构建预览所需的渲染引擎”一节。

搭建前端环境

快速启动

# 默认当前路径为 luban-h5 项目根目录
cd front-end/h5 && yarn && yarn build:engine && yarn dev

# 更多命令请参见 front-end/h5/package.json

yarn dev 启动的是 Vue CLI 开发服务器。关于前端更多可用的脚本,直接查看 front-end/h5/package.json 中的 scripts 字段即可,例如 yarn build:editor(构建编辑器)、yarn build(先后构建 editor 与 engine)、yarn lint(代码检查)、yarn test:e2e 与 yarn test:unit(测试)等。

构建预览所需的渲染引擎

什么是“渲染引擎”?

这是理解 Luban H5 预览机制的核心概念。在 Luban H5 中,一个作品(work)在后端保存的本质是一份 JSON 数据(包含 pages、elements 等结构)。那么,谁来把这份 JSON 转换成手机上真正能看的 H5 页面呢?

答案是:“渲染引擎”。它担当了将作品 JSON 渲染为 H5 页面的重任,主要用于两个场景:

  • 编辑器内的预览弹窗;
  • 用户最终看到的 H5 作品页面。

渲染引擎的入口源码位于 front-end/h5/src/engine-entry.js。该文件注释明确说明:其作用与 src/main.js 类似,都是页面入口,职责是遍历 work(作品)的 pages 与 elements 并完成渲染。从源码结构可以看出,它加载了 core/plugins 中的插件列表、core/editor/canvas/preview 的 RenderPreview 组件、core/preview/node-wrapper.js 的 NodeWrapper,并通过 DataSource.dispatchRequest(window.__work) 在组件创建时派发数据源请求。

如何构建渲染引擎

  1. 在 front-end/h5 目录下运行:yarn build:engine;
  2. 构建完成后,后端的 back-end/h5-api/public 目录下会自动生成一个名为 engine-assets 的文件夹,即渲染引擎产物。

这一行为在 front-end/h5/vue.config.js 中有明确的配置证据:

const engineOutputDir = path.join(__dirname, '../../back-end/h5-api/public/engine-assets')

// 在 switch (process.env.PAGE) 中:
case 'ENGINE':
  page = {
    entry: 'src/engine-entry.js',
    outputDir: engineOutputDir
  }
  break

可以看到,yarn build:engine 对应 package.json 中的 cross-env PAGE=ENGINE vue-cli-service build --target lib --name engine ./src/engine-entry.js,即以库模式(lib)打包 src/engine-entry.js,产物输出到后端的 public/engine-assets 目录,供 Strapi 静态托管。

此外,vue.config.js 中 devServer.proxy 将 /auth|upload|content-manager|users-permissions|works|scripts|datasources|admin|psd-files|workforms|third-libs|engine-assets/ 等路径代理到 http://localhost:1337,这就是开发模式下前端能访问到后端 API 与引擎资源的原因。

渲染引擎的源码级原理

我们从三处源码印证整个渲染链路:

第一处:后端控制器 previewOne

预览接口的核心实现在 back-end/h5-api/api/work/controllers/Work.js#L19-L31:

previewOne: async (ctx) => {
  const { view_mode } = ctx.request.query;
  // https://github.com/strapi/strapi/issues/5688
  const work = await strapi.services.work.findOne({ id: ctx.params.id });
  // 非发布状态, 查看不到内容
  // 非预览模式, 查看不到内容
  const canRender = view_mode === VIEW_MODE.PREVIEW || work.is_publish;
  if (!canRender) work.pages = [];
  work.width = work.width || 320;
  // yarn add strapi-hook-ejs
  return ctx.render('engine', { work });
},

该控制器通过 Strapi 的 EJS 模板引擎渲染 views/engine.ejs 模板(路由为 /works/preview/:id,见 back-end/h5-api/api/work/config/routes.json)。这里有两个值得注意的细节:

  • 只有预览模式(view_mode=preview)或作品已发布(is_publish)时才能渲染,否则 work.pages 会被清空,页面自然无内容可显示;
  • 默认作品宽度为 320px(移动端标准宽度)。

第二处:前端预览弹窗 preview.vue

预览弹窗组件位于 front-end/h5/src/components/core/editor/modals/preview.vue。其核心逻辑是:预览区域本质上是一个 iframe,iframe 的地址为:

previewUrl () {
  return `${window.location.origin}/works/preview/${this.work.id}?view_mode=preview`
}

即在 /works/preview/{id} 后追加 view_mode=preview,与后端 previewOne 中的判定逻辑严格对应。该组件还通过 postMessage2Iframe 向 iframe 内部发送 next / prev 消息,用于控制翻页。

第三处:EJS 模板 engine.ejs

back-end/h5-api/views/engine.ejs 是手机端预览模板,它完成以下工作:

  • 通过 <script>window.__work = <%- JSON.stringify(work) %></script> 将作品 JSON 注入为全局变量;
  • 通过 <script src="/engine-assets/engine.umd.js"></script> 引入刚才构建好的渲染引擎产物;
  • 加载 Vue、Vuex、Swiper、SwiperAnimation、ECharts、v-charts 等 CDN 依赖;
  • 根据 work.width 设置手机视口宽度,并适配移动端与 PC 端(移动端隐藏装饰、PC 端绘制分享二维码);
  • 实例化 Swiper 垂直滚动容器,并在滑动时触发 swiperAnimation 动画,实现多页作品上下滑动切换的体验。

渲染引擎如何工作(从入口源码看)

在 front-end/h5/src/engine-entry.js 中,Engine 组件根据 window.__work.page_mode 判断作品类型:

  • 长页模式(LONG_PAGE):直接渲染第一页的全部元素,容器启用纵向滚动;
  • 滑动翻页模式(默认):将每一页包装为 swiper-slide,由页面上的 Swiper 实例驱动翻页。

同时,渲染前会再次校验 view_mode === 'preview' || work.is_publish,不满足则提示“页面可能暂未发布”。RenderPreview(位于 front-end/h5/src/components/core/editor/canvas/preview)负责把每个 element 实例化为 core/models/element 并渲染。

至此,一条完整的预览链路就清晰了:编辑器保存作品 JSON → 后端 /works/preview/:id 读取作品并渲染 EJS 模板 → 模板注入 window.__work 并加载 engine 产物 → 渲染引擎将 JSON 渲染为可滑动、可交互的手机 H5 页面。

一键脚本:./luban-h5.sh

除了手动分步启动,项目根目录还提供了 luban-h5.sh 一键管理脚本(需先安装 Node > v10、npm、yarn),常用子命令如下:

./luban-h5.sh init        # 安装依赖并编译前后端
./luban-h5.sh start       # 通过 pm2 启动 luban-h5 服务,访问 http://localhost:1337
./luban-h5.sh restart     # 重启服务
./luban-h5.sh stop        # 停止服务
./luban-h5.sh rebuild_fe  # 重新编译编辑器模块和渲染模块
./luban-h5.sh rebuild_engine  # 仅重新编译渲染引擎
./luban-h5.sh rebuild_editor  # 仅重新编译编辑器
./luban-h5.sh clean       # 清理 node_modules、.cache、build 目录
./luban-h5.sh version     # 查看版本

从脚本实现(luban-h5.sh)可以看到,init 会先在前端目录执行 yarn && yarn build(编译核心编辑器 + 预览引擎),再在后端目录执行 yarn && NODE_ENV=production yarn build;start 则通过 pm2 start --name luban-h5-service server.js 以后台进程方式启动后端服务。如果你在安装 sqlite3、node-gyp 等原生模块时遇到编译报错,可先执行 ./deploy/mirror.sh 将 npm 镜像切换为阿里云镜像(特别用于解决二进制包安装问题)。

本地开发常见问题速查

现象 原因 解决方案
接口返回 403 Forbidden Public 角色未开放接口权限 管理后台 Roles And Permission → Public → Permissions 中勾选对应权限(含上传作品封面图所需权限)
预览弹窗显示空白 未构建预览渲染引擎 在 front-end/h5 下执行 yarn build:engine,确认后端 public/engine-assets 已生成
依赖安装报错(sqlite3、node-gyp) 原生模块编译或网络问题 执行 ./deploy/mirror.sh 切换阿里云镜像后重新安装
后端无法启动 Node 版本不匹配 使用 Node LTS(v10 或 v12),满足 >=10.16.0 <=14.x.x

结语

本文围绕 Luban H5 官方 Quick Start 文档,完整覆盖了前后端本地环境搭建、管理后台权限配置、渲染引擎的构建方法及其背后“作品 JSON → EJS 模板注入 → 渲染引擎 → 手机 H5 页面”的完整调用链。如果你在本地开发中遇到文档未尽的问题,可以对照 front-end/h5/package.json、back-end/h5-api/package.json 与 front-end/h5/vue.config.js 等源码进一步排查,也可以在仓库的 docs 目录中继续阅读部署与迁移相关文档。

更多资源指引:

登录后查看全文
luban-h5