H5 活动页工程化复盘：从模板到自动化搭建平台的演进

H5 活动页工程化复盘：从模板到自动化搭建平台的演进

一、活动页开发的生产力困境：高频迭代与低效手写的矛盾

运营活动页是前端领域"高频、短生命周期、高视觉要求"的典型场景。一家中型电商公司每月可能需要上线 2030 个不同的活动页——双11专题、618大促、品牌日、会员日、新品首发……每个页面的生命周期通常在 315 天，但视觉风格和交互玩法各有差异。

传统开发模式下的生产流程是：运营提交 PRD → 设计师出图 → 前端切图还原 → 联调数据接口 → 测试 → 上线。这个流程存在三个核心矛盾：

1. 人力瓶颈：活动密集期，前端团队的工作量是日常的 3~5 倍，而团队的扩张跟不上业务需求的波动。
2. 重复劳动：同一个前端工程师本月可能要做 5 个抽奖页面，每个页面的核心逻辑（转盘动画、中奖概率、领奖逻辑）大同小异，但每次都要从头写一遍。
3. 质量参差：在高压交付下，代码复用靠的是 Ctrl+C/V。样式不一致、动画卡顿、边界状态缺失等问题频繁出现。

工程化的目标是：将前端工程师从重复的页面搭建工作中解放出来，让他们专注于组件的开发和平台的优化，而将页面组装交给运营和设计人员。

二、阶段一：模板时代——从零到一的快速交付

2.1 模板项目的结构设计

第一版活动页模板的核心设计原则是"90% 的场景覆盖在模板变量中完成"。一个典型的活动页模板包含以下可配置维度：

• 视觉主题：主色调、背景图、字体、按钮样式。
• 页面结构：头部 Banner、商品列表（单排/双排/瀑布流）、抽奖模块、倒计时模块、规则弹窗。
• 数据源：商品数据接口、抽奖配置、活动时间规则。
• 埋点：页面曝光、模块曝光、按钮点击、分享行为。

模板不是静态的 HTML 文件，而是一个基于create-vite初始化的独立项目。每个新活动由前端工程师 fork 模板项目，修改config.json和替换素材资源后部署。

2.2 模板复制的痛点

模板方案在活动量 < 10 个/月时运转良好，但活动量达到 20+/月时暴露了三个问题：

• 分支管理灾难：每个活动是一个独立仓库（或独立分支），30 个活动意味着 30 份几乎相同的代码。当抽奖组件需要修复一个 Bug 时，需要在 30 个地方同步修复。
• 非开发人员的发布依赖：运营想改一个文案颜色，需要发 PR → 找前端 review → 合并 → 触发构建。流程太慢。
• 模板的边界模糊：当一个活动需求超出模板能力时（如"在抽奖结果页加一个分享助力功能"），前端需要"在模板基础上改"，结果改完之后这个活动页面就无法被模板更新覆盖了。

三、阶段二：CLI 工具 + 配置化——从复制代码到声明式生成

3.1 活动页脚手架的设计

CLI 工具解决了模板时代"分支爆炸"和"同步修复困难"的问题。核心思路是：模板不再是一个仓库，而是一个可通过 CLI 拉取的脚手架。每次生成活动页时，CLI 根据activity.config.json动态组合组件，生成单次使用的项目代码。

/** * 活动页 CLI 脚手架生成器 * 根据配置文件动态组合组件，生成项目代码 */ import { Command } from 'commander'; import { input, select, confirm } from '@inquirer/prompts'; import * as fs from 'fs-extra'; import * as path from 'path'; import Handlebars from 'handlebars'; interface ActivityConfig { name: string; type: 'lottery' | 'flash_sale' | 'brand_day' | 'custom'; theme: { primaryColor: string; bgImage: string; fontFamily: string; }; modules: ModuleConfig[]; dataSource: DataSourceConfig; tracking: TrackingConfig; } interface ModuleConfig { type: string; // 'banner' | 'countdown' | 'product_list' | 'lottery' | 'share' position: number; props: Record<string, unknown>; } interface DataSourceConfig { productApi: string; lotteryApi: string; userApi: string; mockEnabled: boolean; } interface TrackingConfig { reportUrl: string; pageId: string; } class ActivityGenerator { private templateDir: string; constructor(templateDir: string) { this.templateDir = templateDir; } async generate(config: ActivityConfig, outputDir: string): Promise<void> { // 1. 复制基础模板结构（Vite + React） await fs.copy( path.join(this.templateDir, 'base'), outputDir ); // 2. 收集需要的组件列表（去重） const requiredComponents = this.collectComponents(config.modules); // 3. 复制组件源码到项目中 for (const comp of requiredComponents) { await fs.copy( path.join(this.templateDir, 'components', comp), path.join(outputDir, 'src/components', comp) ); } // 4. 生成入口文件：根据配置动态组装模块 const appContent = this.renderAppTemplate(config); await fs.writeFile( path.join(outputDir, 'src/App.tsx'), appContent ); // 5. 生成组件注册文件：只导入实际使用的组件 const registryContent = this.renderComponentRegistry(requiredComponents); await fs.writeFile( path.join(outputDir, 'src/components/registry.ts'), registryContent ); // 6. 生成样式变量文件 const styleContent = this.renderThemeStyles(config.theme); await fs.writeFile( path.join(outputDir, 'src/styles/theme.css'), styleContent ); console.log(`✅ 活动 ${config.name} 生成完成`); console.log(` 组件数量：${requiredComponents.length}`); console.log(` 模块数量：${config.modules.length}`); } private collectComponents(modules: ModuleConfig[]): string[] { const typeToComponent: Record<string, string> = { banner: 'Banner', countdown: 'CountdownTimer', product_list: 'ProductList', lottery: 'LotteryWheel', share: 'SharePanel', rule_dialog: 'RuleDialog', coupon: 'CouponCard', }; const components = new Set<string>(); for (const mod of modules) { const name = typeToComponent[mod.type]; if (name) components.add(name); } return Array.from(components); } private renderAppTemplate(config: ActivityConfig): string { // 使用 Handlebars 动态渲染 App.tsx const template = Handlebars.compile(` import React from 'react'; import './styles/theme.css'; import { DataProvider } from './hooks/useActivityData'; {{#each imports}} import {{name}} from './components/{{name}}'; {{/each}} export default function App() { const modules = {{json modules}}; return ( <DataProvider config={config}> <div className="activity-page"> {modules .sort((a, b) => a.position - b.position) .map(mod => renderModule(mod))} </div> </DataProvider> ); } function renderModule(mod) { switch (mod.type) { {{#each moduleCases}} case '{{type}}': return <{{component}} key={mod.type} {...mod.props} />; {{/each}} default: return null; } } `); const imports = this.collectComponents(config.modules).map((name) => ({ name })); const moduleCases = config.modules.map((m) => ({ type: m.type, component: this.typeToComponent(m.type), })); return template({ imports, modules: config.modules, moduleCases, configJson: JSON.stringify(config) }); } private renderThemeStyles(theme: ActivityConfig['theme']): string { return ` :root { --primary-color: ${theme.primaryColor}; --bg-image: url(${theme.bgImage}); --font-family: ${theme.fontFamily}; } `.trim(); } private renderComponentRegistry(components: string[]): string { return components .map((name) => `export { default as ${name} } from './${name}';`) .join('\n'); } private typeToComponent(type: string): string { const map: Record<string, string> = { banner: 'Banner', countdown: 'CountdownTimer', product_list: 'ProductList', lottery: 'LotteryWheel', share: 'SharePanel', rule_dialog: 'RuleDialog', coupon: 'CouponCard', }; return map[type] || 'Unknown'; } } export { ActivityGenerator }; export type { ActivityConfig, ModuleConfig, DataSourceConfig, TrackingConfig };

3.2 配置化的收益

CLI 方案带来的直接收益：

• 新活动创建时间：从 30 分钟（复制项目 + 修改代码 + 本地调试）降到 3 分钟（写配置文件 + 一条 CLI 命令）。
• Bug 修复同步：修改组件源码后，通过 CLI 重新生成所有使用该组件的活动项目即可同步修复。
• 组件组合灵活性：配置文件中可以任意组合模块和它们的 props，超出模板能力的"定制化"需求可以通过注册自定义组件来处理。

四、阶段三：可视化搭建平台——从开发者工具到运营工具

4.1 平台架构设计

CLI 工具虽然解决了开发效率问题，但没有解决"运营自己改页面"的核心诉求。可视化搭建平台的设计目标是：运营通过拖拽和配置面板完成页面的创建和发布，不需要前端介入。

平台的核心架构包括四个模块：

• 可视化编辑器：左侧组件面板（可搜索、可分类）、中间画布（实时预览、拖拽排序）、右侧属性面板（可配置每个组件的 props）。
• 组件市场：每个组件有独立的版本号、依赖声明、文档。支持灰度发布（新增组件默认关闭，需手动开启）。
• DSL 渲染引擎：编辑器输出的 JSON Schema 通过渲染引擎实时生成页面。渲染引擎与编辑器共用同一套组件实现，保证编辑态和发布态完全一致。
• 数据源接入：统一的数据接口网关，组件通过声明式配置关联数据源，运行时自动拉取和注入数据。

4.2 DSL（Domain Specific Language）设计

搭建平台的核心是 DSL——一种描述页面结构和组件配置的 JSON 格式。DSL 需要满足三个条件：对人类可读（运营可以理解 JSON 的大致含义）、对机器可解析（渲染引擎可递归解析和渲染）、对迁移兼容（版本升级时不影响已有页面）。

/** * 活动页 DSL 规范 * 描述页面的完整结构，由可视化编辑器生成，渲染引擎解析 */ interface ActivityDSL { version: '1.0'; meta: { id: string; name: string; createdAt: string; updatedAt: string; status: 'draft' | 'published' | 'archived'; }; theme: { primaryColor: string; backgroundColor: string; backgroundImage?: string; globalPadding?: number; }; pages: PageDSL[]; globalData?: DataSourceDSL[]; } interface PageDSL { id: string; name: string; modules: ModuleDSL[]; dataSources?: DataSourceDSL[]; } interface ModuleDSL { id: string; componentKey: string; // 组件的全局唯一标识，如 'LotteryWheel@1.2.0' props: Record<string, unknown>; style?: Record<string, string>; animations?: AnimationDSL[]; events?: EventDSL[]; children?: ModuleDSL[]; // 支持嵌套（如容器组件） } interface AnimationDSL { type: 'fadeIn' | 'slideUp' | 'bounce' | 'custom'; duration: number; delay: number; easing: string; keyframes?: KeyframeDSL[]; } interface EventDSL { trigger: 'onClick' | 'onViewport' | 'onTimer'; action: 'navigate' | 'showDialog' | 'track' | 'callApi'; params: Record<string, unknown>; } interface DataSourceDSL { key: string; type: 'api' | 'static' | 'computed'; config: { url?: string; method?: 'GET' | 'POST'; params?: Record<string, unknown>; responseMapping?: string; // JSONPath 表达式提取数据 fallback?: unknown; }; } /** * DSL 渲染引擎：递归解析 DSL 并渲染为 React 组件树 */ class DSLRenderer { private componentRegistry: Map<string, React.ComponentType<any>>; constructor(registry: Map<string, React.ComponentType<any>>) { this.componentRegistry = registry; } renderPage(page: PageDSL): React.ReactNode { return ( <div className={`page-${page.id}`}>