#  h5-activity-starter

**Repository Path**: jules2009/h5-activity-starter

## Basic Information

- **Project Name**:  h5-activity-starter
- **Description**: 一个面向活动页、落地页、核销页和 App 唤起页的多页面 H5 脚手架。
- **Primary Language**: JavaScript
- **License**: MIT-0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# h5-video-course

基于 Vite 8 + TypeScript 的多页面 H5 活动页项目。

项目不是传统 SPA，而是统一管理多个独立访问的 H5 页面，例如落地页、核销页、渠道活动页、App 唤起页。每个页面都有独立 HTML 入口、独立样式和页面逻辑，但共享同一套构建、样式策略和基础工具。

## 技术栈

- 构建：Vite 8
- 语言：TypeScript 6
- 样式：Less + PostCSS `px -> vw`
- 架构：MPA（Multi-Page Application）
- 规范：ESLint + Prettier

## 当前特性

- 多页面入口统一由 Vite 构建
- 页面清单集中维护在 `src/shared/config/pages.ts`
- 开发导航页自动读取页面配置生成链接
- 新页面可通过 `create:page` 脚手架快速创建
- 页面展示配置、业务配置、资源配置逐步收口到 `src/shared/config/`
- 支持局域网访问，方便真机联调

## 运行要求

- Node.js >= 18
- npm >= 9

## 常用命令

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build

# 测试环境构建
npm run build:test

# 预发环境构建
npm run build:pre

# 预览构建结果
npm run preview

# 新增页面脚手架
npm run create:page -- --name demoCampaign --title "演示活动页"

# 仅预览脚手架输出，不写文件
npm run create:page -- --name demoCampaign --title "演示活动页" --dry-run

# 代码检查
npm run lint

# 代码格式化
npm run format
```

## 页面入口

启动开发环境后，默认访问：

- 开发导航页：`http://localhost:5173/`

当前已有页面：

- 落地页：`http://localhost:5173/landing.html`
- 核销页：`http://localhost:5173/verify.html`

## 项目结构

```text
.
├─ public/
│  ├─ favicon.svg
│  └─ icons.svg
├─ scripts/
│  └─ create-page.mjs
├─ src/
│  ├─ assets/
│  │  ├─ hero.png
│  │  ├─ images/
│  │  └─ styles/
│  ├─ pages/
│  │  ├─ landing/
│  │  ├─ verify/
│  ├─ shared/
│  │  ├─ config/
│  │  ├─ styles/
│  │  └─ utils/
│  ├─ main.ts
│  ├─ style.css
│  └─ vite-env.d.ts
├─ .env
├─ .env.example
├─ index.html
├─ landing.html
├─ verify.html
├─ package.json
├─ tsconfig.json
└─ vite.config.ts
```

## 页面配置机制

### 1. 页面入口清单

页面入口清单位于：

- `src/shared/config/pages.ts`

这份配置承担两件事：

1. 提供 Vite 多页面构建入口
2. 提供开发导航页展示的页面列表

单个页面配置示例：

```ts
{
  key: "verify",
  name: "verify",
  htmlFile: "verify.html",
  entryFile: "/src/pages/verify/main.ts",
  navLabel: "核销页",
  showInIndex: true,
}
```

字段说明：

- `key`：页面唯一标识，用于构建入口映射
- `name`：页面目录名
- `htmlFile`：规范入口 HTML 文件
- `entryFile`：页面入口脚本
- `navLabel`：开发导航页展示名称
- `showInIndex`：是否显示在开发导航页

### 2. 页面内容配置

当前页面内容和资源配置逐步收口到：

- `src/shared/config/landing.ts`
- `src/shared/config/verify.ts`
- `src/shared/config/page-content.ts`

目前正在统一到以下结构：

- `meta`：页面元信息
- `content`：页面主体展示内容
- `actions`：页面按钮配置
- `assets`：页面资源路径
- `behavior`：跳转地址等行为配置

`landing`、`verify` 已按标准活动页配置方式读取。

## 新增页面方式

推荐使用脚手架：

```bash
npm run create:page -- --name courseReceive --title "课程领取页"
```

脚手架会自动完成：

- 创建 `src/pages/courseReceive/`
- 生成 `main.ts`
- 生成 `style.less`
- 创建 `assets/` 目录
- 创建根目录 `courseReceive.html`
- 追加页面配置到 `src/shared/config/pages.ts`

脚手架生成的不是空白页面，而是一套标准活动页模板，默认包含：

- `@/shared/styles/reset.less`
- `@/shared/styles/activity-page.less`
- 标准 `activity-page` 命名结构
- 默认标题、说明区和“开发提示”区块
- `px -> vw` 样式基线

创建完成后可直接访问：

```bash
http://localhost:5173/courseReceive.html
```

如果只想预览脚手架行为：

```bash
npm run create:page -- --name courseReceive --title "课程领取页" --dry-run
```

### 新增页面最小示例

1. 先创建页面：

```bash
npm run create:page -- --name summerCampaign --title "夏季活动页"
```

2. 在 `src/shared/config/` 新增页面配置，例如：

```ts
import heroImage from "@/assets/images/landing-bg.png";
import type { StandardActivityPageConfig } from "./page-content";

export const summerCampaignConfig: StandardActivityPageConfig = {
  meta: {
    key: "summerCampaign",
    title: "夏季活动页",
  },
  content: {
    eyebrow: "SUMMER CAMPAIGN",
    title: "夏季活动页",
    description: "这是一个最小配置示例。",
    sections: [
      {
        title: "活动说明",
        tips: ["页面文案放配置里", "跳转地址放 behavior 里"],
      },
    ],
  },
  actions: {
    primary: {
      label: "立即参与",
      action: "jump",
    },
  },
  assets: {
    backgroundImage: heroImage,
  },
  behavior: {
    targetUrl: "https://example.com",
  },
};
```

3. 在 `src/pages/summerCampaign/main.ts` 消费配置：

```ts
import "@/shared/styles/reset.less";
import "@/shared/styles/activity-page.less";
import "./style.less";
import { createPage, renderActivityPage } from "@/shared/utils";
import { summerCampaignConfig } from "@/shared/config";

const backgroundImage = summerCampaignConfig.assets?.backgroundImage ?? "";
const primaryAction = summerCampaignConfig.actions?.primary;

createPage({
  template: `
    <div class="landing-page" style="--landing-bg: url(${backgroundImage})">
      ${renderActivityPage({
        ...summerCampaignConfig.content,
        actions: primaryAction ? [primaryAction] : [],
      })}
    </div>
  `,
  events: {
    "click [data-action=jump]": () => {
      const targetUrl = summerCampaignConfig.behavior?.targetUrl;
      if (targetUrl) {
        window.location.href = targetUrl;
      }
    },
  },
});
```

4. 本地验证：

```bash
npm run dev
# 打开 http://localhost:5173/summerCampaign.html
```

## 页面命名规范

新增页面时，建议统一遵守以下命名规则：

- 页面目录名使用英文，优先使用小驼峰，例如 `courseReceive`、`summerCampaign`
- HTML 文件名默认与页面目录名保持一致，例如 `courseReceive.html`
- 页面配置中的 `key` 与目录名语义一致，由脚手架自动生成
- 不要在页面目录名中使用中文、空格或特殊字符
- 不建议混用全大写命名，历史页面建议逐步迁移到小驼峰命名，并保留兼容入口

推荐示例：

- `courseReceive`
- `appLaunchGuide`
- `newUserCampaign`
- `midAutumnLanding`

不推荐示例：

- `课程领取页`
- `course-receive-page`
- `Course_Receive`
- `page 01`

## 页面开发规范

### 目录结构

标准页面目录：

```text
src/pages/xxx/
├─ main.ts
├─ style.less
└─ assets/
```

复杂页面可以额外拆模板或局部渲染文件：

### 规范清单

- `main.ts` 负责页面渲染、状态流转和交互逻辑
- `style.less` 负责页面样式，优先直接写 `px`
- 页面入口优先引入 `@/shared/styles/reset.less`
- 标准活动页优先复用 `@/shared/styles/activity-page.less`
- 页面私有资源放当前页面目录；可复用资源放 `src/assets/`
- 页面通用逻辑放 `src/shared/utils/`；展示内容、资源路径、行为配置优先放 `src/shared/config/`
- 页面入口、导航名称、HTML 文件统一通过 `src/shared/config/pages.ts` 管理
- 业务跳转链接、渠道参数、App 唤起地址等不要散落在模板字符串中
- 文案、按钮状态、异常提示尽量集中定义，避免硬编码散落
- 页面 DOM 结构保持简单，class 命名保持语义化
- 不要把多个活动页的专属逻辑混写到同一个页面目录里

### 样式约束

- 自适应统一交给 PostCSS `px -> vw`
- 视口和安全区场景保留使用 `vh`、`svh`、`dvh`、`env()`、`clamp()`
- 除非是历史兼容页面，不再新增运行时 `rem` 自适应逻辑
- 公共颜色、字号、基础变量优先复用 `src/assets/styles/variables.less`

### 新增页面流程

1. 使用脚手架创建页面。
2. 在页面目录内补充业务内容。
3. 按需要把文案、资源、跳转地址抽到 `src/shared/config/`。
4. 本地通过开发导航页或直接访问 HTML 验证。
5. 执行 `npm run build` 确认页面可参与构建。

## 样式策略

项目当前统一方案：

- 设计稿宽度按 `750`
- Less 中直接写 `px`
- 构建阶段通过 `postcss-px-to-viewport-8-plugin` 转换为 `vw`

配置位置：

- `vite.config.ts`

保留原生视口单位的场景：

- `vh`
- `svh`
- `dvh`
- `%`
- `env(safe-area-inset-*)`
- `clamp()`

## 构建说明

当前支持：

- `npm run build`
- `npm run build:test`
- `npm run build:pre`

构建入口由 `vite.config.ts` 联动 `src/shared/config/pages.ts` 自动生成。

## 环境变量

项目通过 Vite 的环境变量机制读取配置，约定：

- 自定义变量必须以 `VITE_` 开头

示例：

```ts
const apiUrl = import.meta.env.VITE_API_BASE_URL;
const env = import.meta.env.VITE_APP_ENV;
```

当前仓库提供的示例变量见 `.env.example`：

- `VITE_APP_TITLE`
- `VITE_APP_ENV`
- `VITE_API_BASE_URL`

初始化本地环境：

```bash
cp .env.example .env
```

当前仓库已包含本地 `.env` 默认值，至少提供了：

- `VITE_APP_TITLE`

它用于替换各个 HTML 入口中的 `<title>`，避免构建阶段出现标题变量未定义告警。

## 当前维护方式总结

当前仓库已经从“每个活动页单独一个项目”收口为“一个仓库统一管理多个 H5 页面”，并进一步演进到：

- 页面入口清单集中管理
- 导航页自动渲染
- 新页面可用脚手架创建
- 标准活动页样式和结构可复用
- 页面展示配置、资源配置、行为配置逐步配置驱动化

在维持多页面目录结构不变的前提下，这显著降低了新增页面和收口历史页面时的重复修改成本。