Luban H5 本地开发环境搭建与预览渲染引擎构建全指南
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 管理后台
# 请继续阅读,进行相关配置
几点需要特别说明:
- 为何必须用 yarn 而非 npm 安装依赖? 这与项目依赖的解析方式相关(详见原文档引用的 issue 讨论),如果你使用 npm 遇到安装或启动异常,请切换回 yarn 重新安装。
- 本地调试命令:文档提到在 VSCode 中调试可运行
yarn localdev,它通过调试端口启动 Strapi 服务,方便打断点跟踪后端代码。 - 数据库位置:默认使用 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 角色。解决步骤如下:
- 访问 http://localhost:1337/admin;
- 进入 Roles And Permission → Public → Permissions;
- 为需要公开访问的接口勾选对应权限,使其可被匿名访问。
其中有一项权限是专门**用于上传作品封面图(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) 在组件创建时派发数据源请求。
如何构建渲染引擎
- 在
front-end/h5目录下运行:yarn build:engine; - 构建完成后,后端的
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 目录中继续阅读部署与迁移相关文档。
更多资源指引: