游戏联动活动页看起来只是几张图加一段动画,真正上线后却经常在开服十几分钟内暴露问题:首屏白屏、动画掉帧、倒计时和服务器时间对不上、某个机型上整块图层错位。以《第五人格》与上海美术电影制片厂《九色鹿》联动这种带明显美术风格的主题为例,页面既要还原水墨质感的视觉,又要在活动开启瞬间承接集中涌入的访问量,还要保证用户在各类内置浏览器里能看到完整内容。这类页面的工程难度不在“写一个页面”,而在“把素材、时间轴、加载策略和降级方案组织成一套可验证、可回滚的实现”。
下面按一条完整主线展开:先拆解联动活动页的压力来源,再搭出可运行的工程骨架,接着实现时间轴动画、素材预加载、倒计时状态机,最后给出真机排查链路和生产环境的上线清单。示例代码使用 TypeScript 与原生 Canvas/DOM,不依赖特定框架,读者可以按自己项目的技术栈迁移。文中涉及的联动素材名称、上线时间、活动规则等内容属于运营信息,落地时必须以官方发布为准,代码部分只讨论工程做法。
1. 联动活动页为什么不能当成普通静态页面来做
很多团队在评估工作量时,会把这类页面归类为“静态页 + 动画”,按普通活动页的人力投入排期。等到压测或者真实上线,问题集中爆发:首屏图片没加载完,用户先看到一片空白;动画在低端安卓机上掉到十几帧;倒计时结束时页面没有自动切换到结束态;某个 WebView 里 Canvas 绘制的纹理直接错位。这些问题不是代码写得糙,而是设计阶段没有把活动页的真实压力模型考虑进去。
1.1 活动页的三类核心压力
第一类是瞬时流量。活动开启的时间点是确定的,用户行为高度集中,前几分钟的并发可能是日常访问的几十倍。这类流量对静态资源服务器的压力远大于对业务接口的压力,因为绝大多数请求都是图片、字体和脚本。
第二类是素材体积。联动主题的美术资源通常是高分辨率插画、分层序列帧、特殊字体。一张 2000×3000 的主视觉 PNG 未压缩可能有 8 到 12 MB,序列帧动辄几十张。如果按“先全部加载完再展示”的思路做,首屏时间会被拉到无法接受的程度。
第三类是动画节奏。美术给的是按秒描述的分镜节奏,前端要把它翻译成时间轴;一旦某一步等待素材加载,整条时间轴就会和音效、文案错位。动画不是装饰,它和页面状态强绑定。
把这三类压力放在一起看,就能理解为什么联动活动页需要单独的工程结构,而不是把图片往 HTML 里一贴就交付。
1.2 素材分层决定首屏能多快出现
处理大素材最有效的办法不是压缩算法,而是分层。实际操作中,可以按“是否必须在第一帧出现”把素材分成三组:
- 首屏关键组:背景底色、主视觉的低清占位、首屏文案字体子集。这组必须进入关键路径,体积控制在 300 KB 以内。
- 交互组:点击后才出现的分层插画、按钮态、弹窗素材。这组在首屏渲染完成后空闲时段预加载。
- 装饰组:粒子、光效、序列帧。这组按需加载,并且在低端设备上可以直接关闭。
分层之后,加载策略就有了明确的优先级,而不是靠一个巨大的 Promise.all 等待全部完成。下面这张表是常见项目的分层参考,具体体积阈值要结合自家 CDN 和用户网络分布调整。
| 分层 | 典型内容 | 体积建议 | 加载时机 | 失败后表现 |
|---|---|---|---|---|
| 首屏关键组 | 背景、低清主视觉、核心字体子集 | 小于 300 KB | 页面 HTML 解析时同步发起 | 页面不可用,必须重试 |
| 交互组 | 分层插画、按钮图、弹窗底图 | 单张小于 200 KB | 首屏完成后 requestIdleCallback |
局部降级为纯色块 |
| 装饰组 | 光效、粒子、序列帧 | 总量小于 1.5 MB | 用户触发或动画进入该阶段 | 静默跳过,不影响主流程 |
注意:分层不是一次性决定。素材交付后要跑一次真实网络环境下的加载瀑布图,确认首屏关键组的请求确实排在最前面,避免被第三方统计脚本或字体文件挤到后面。
1.3 设计阶段就要定下来的四个指标
没有指标的优化都是猜。联动活动页至少要在需求评审阶段就把下面四个指标写进验收标准,否则上线后无法判断“能不能发”。
| 指标 | 含义 | 建议目标 | 采集方式 |
|---|---|---|---|
| 首屏可见时间 | 从导航开始到主视觉可见 | 4G 网络下不超过 2.5 s | PerformanceObserver 监听 LCP 或自定义打点 |
| 动画平均帧率 | 主时间轴播放期间的平均 FPS | 中端机型不低于 50 | 采样 rAF 间隔,统计超过 33 ms 的比例 |
| 素材加载失败率 | 关键组素材请求失败占比 | 低于 1% | 资源 onerror 上报 |
| 峰值内存 | 页面稳定后的 JS 堆与纹理占用 | 移动端低于 200 MB | performance.memory 或真机 profiler |
这里要注意一个容易误解的点:帧率指标不能用平均值单独判断。平均值 55 帧可能意味着大部分时间 60 帧、偶尔掉到 10 帧,用户感知到的就是明显卡顿。统计“超过 33 ms 的帧占比”比平均值更有诊断价值。
1.4 学习环境和生产环境的差别
本地开发时,素材放在 public 目录,浏览器缓存全开,动效流畅,很容易得出“性能没问题”的结论。真实环境完全不同:CDN 回源、运营商网络抖动、WebView 版本碎片化、系统省电模式降频。所以从第一天起就要区分两套验证方式。
学习环境追求快速跑通,用本地静态服务即可;生产环境必须补齐缓存策略、资源指纹、失败重试、监控上报和回滚通道。这些内容会在后面几节逐一展开。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 工程结构与依赖准备:先把素材清单变成可编译的输入
联动活动页的返工大多来自素材变更:美术改了一版主视觉、运营换了一张按钮图、法务要求替换某个文案。如果代码里到处是硬编码的路径字符串,每次替换都要全局搜索。合理的做法是把素材抽象成一份清单文件,由脚本生成,代码只引用清单里的键名。
2.1 目录结构
下面是一个可以直接落地的最小结构,框架无关,换成 Vue 或 React 也不影响分层思路。
text复制event-page/
├── public/
│ └── favicon.ico
├── scripts/
│ └── build-manifest.mjs # 扫描素材目录生成清单
├── src/
│ ├── assets/
│ │ ├── key/ # 首屏关键组
│ │ ├── interactive/ # 交互组
│ │ └── decor/ # 装饰组
│ ├── core/
│ │ ├── loader.ts # 预加载队列
│ │ ├── timeline.ts # 时间轴播放器
│ │ ├── clock.ts # 服务端时间校准
│ │ └── reporter.ts # 埋点与错误上报
│ ├── scene/
│ │ ├── intro.ts # 开场动画
│ │ └── main.ts # 主界面交互
│ ├── styles/
│ │ └── base.css
│ └── main.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
目录按“职责”划分而不是按“文件类型”划分,是为了让改动范围可预测:换素材只动 assets 和清单,调播放逻辑只动 core/timeline.ts,改交互只动 scene。
2.2 依赖与构建配置
依赖要克制。活动页的寿命通常只有几周,引入大型 UI 库或状态管理框架,收益远小于维护成本。
json复制{
"name": "event-page",
"private": true,
"type": "module",
"scripts": {
"dev": "vite --host",
"build": "node scripts/build-manifest.mjs && vite build",
"preview": "vite preview --port 4173"
},
"devDependencies": {
"typescript": "^5.4.0",
"vite": "^5.2.0"
}
}
构建脚本里先执行清单生成,再执行打包,这个顺序不能反。否则打包时清单还是旧版本,会引用到已经被替换掉的文件名。
下面是构建配置,重点在资源内联阈值和输出文件名策略。
ts复制// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
base: '/act/2024-deer/',
build: {
target: 'es2018',
assetsInlineLimit: 4096, // 4KB 以下内联为 base64,减少请求数
chunkSizeWarningLimit: 800,
rollupOptions: {
output: {
assetFileNames: 'static/[name]-[hash:8][extname]',
chunkFileNames: 'static/[name]-[hash:8].js',
entryFileNames: 'static/[name]-[hash:8].js',
},
},
},
});
assetsInlineLimit 设成 4 KB 是一个折中值。太大会让 HTML 体积膨胀、失去并行下载优势;太小则请求数过多。超过 4 KB 的图标建议单独走 CDN。
base 必须和实际部署路径一致。这一项配错,表现是页面白屏但控制台只有 404,很多人会在业务代码里找半天。
2.3 用脚本生成素材清单
手工维护清单迟早出错。写一个扫描脚本,把文件名、分层、尺寸、预估体积整理成 JSON,代码按 key 引用。
js复制// scripts/build-manifest.mjs
import { readdir, stat, writeFile } from 'node:fs/promises';
import { join, extname, basename } from 'node:path';
const GROUPS = ['key', 'interactive', 'decor'];
const ROOT = 'src/assets';
const manifest = {};
for (const group of GROUPS) {
const dir = join(ROOT, group);
let files = [];
try {
files = await readdir(dir);
} catch {
manifest[group] = [];
continue;
}
const entries = [];
for (const file of files) {
if (!['.png', '.jpg', '.webp', '.mp3', '.json'].includes(extname(file))) continue;
const info = await stat(join(dir, file));
entries.push({
key: `${group}/${basename(file, extname(file))}`,
src: `/src/assets/${group}/${file}`,
bytes: info.size,
});
}
manifest[group] = entries.sort((a, b) => a.bytes - b.bytes);
}
await writeFile('src/assets/manifest.json', JSON.stringify(manifest, null, 2), 'utf8');
console.log('manifest generated:', Object.keys(manifest).map(k => `${k}=${manifest[k].length}`).join(', '));
脚本按体积升序排列,是为了让后续预加载时小图先到,尽快出现可视内容。清单里保留 bytes 字段,可以在运行时判断当前网络下是否跳过装饰组。
生成后的清单长这样:
json复制{
"key": [
{ "key": "key/bg-base", "src": "/src/assets/key/bg-base.webp", "bytes": 41230 },
{ "key": "key/main-visual-low", "src": "/src/assets/key/main-visual-low.webp", "bytes": 128400 }
],
"interactive": [
{ "key": "interactive/btn-primary", "src": "/src/assets/interactive/btn-primary.png", "bytes": 18300 }
],
"decor": []
}
注意:素材授权范围要和法务确认清楚。联动主题的美术资源通常只允许在指定域名和指定周期内使用,不建议让第三方 CDN 缓存,也不应把原图直接暴露在可长期访问的地址上。
3. 用时间轴驱动动画:把美术的分镜翻译成数据结构
联动主题的动画往往有明确的叙事节奏:先出现背景,再浮现主体,最后文字落版。如果把这套节奏写成一串 setTimeout,改一次时长就要重新数一遍嵌套层级,而且无法暂停、无法回放、无法降级。正确的做法是把时间轴抽象成数据,由播放器统一调度。
3.1 时间轴的数据结构
每个动画单元描述“在什么时间、对哪个元素、做什么”,播放器只负责按时间推进。
ts复制// src/core/timeline.ts
export type Easing = 'linear' | 'easeOut' | 'easeInOut';
export interface Track {
id: string; // 目标元素选择器或 canvas 图层名
start: number; // 相对时间轴的开始时间,单位 ms
duration: number; // 持续时长,单位 ms
from: Record<string, number>;
to: Record<string, number>;
easing?: Easing;
}
export interface TimelineConfig {
total: number;
tracks: Track[];
}
下面是一份实际可用的配置,描述开场三秒的节奏:
ts复制// src/scene/intro.ts
import type { TimelineConfig } from '../core/timeline';
export const introTimeline: TimelineConfig = {
total: 3200,
tracks: [
{ id: '#bg', start: 0, duration: 800, from: { opacity: 0 }, to: { opacity: 1 }, easing: 'linear' },
{ id: '#main-visual', start: 600, duration: 1200, from: { opacity: 0, scale: 0.92 }, to: { opacity: 1, scale: 1 }, easing: 'easeOut' },
{ id: '#title', start: 1600, duration: 900, from: { opacity: 0, y: 24 }, to: { opacity: 1, y: 0 }, easing: 'easeOut' },
{ id: '#cta', start: 2500, duration: 500, from: { opacity: 0 }, to: { opacity: 1 }, easing: 'linear' },
],
};
数据化的好处很直接:美术改节奏只需要改数字,不用碰调度逻辑;单元测试可以对配置做静态校验,比如检查是否存在 start + duration > total 的越界项。
3.2 播放器实现与帧预算控制
播放器基于 requestAnimationFrame 推进,核心是把真实经过的时间映射到时间轴位置,而不是靠累加每帧的固定增量。后者在掉帧时会导致动画变慢,音画不同步。
ts复制// src/core/timeline.ts
const EASING: Record<string, (t: number) => number> = {
linear: t => t,
easeOut: t => 1 - Math.pow(1 - t, 3),
easeInOut: t => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
};
export class TimelinePlayer {
private rafId = 0;
private startAt = 0;
private paused = false;
private pausedAt = 0;
constructor(
private config: TimelineConfig,
private resolve: (id: string) => HTMLElement | null,
private onFrame?: () => void,
private onDone?: () => void,
) {}
play(): void {
this.startAt = performance.now();
const step = (now: number) => {
if (this.paused) return;
const elapsed = now - this.startAt;
this.apply(elapsed);
this.onFrame?.();
if (elapsed < this.config.total) {
this.rafId = requestAnimationFrame(step);
} else {
this.onDone?.();
}
};
this.rafId = requestAnimationFrame(step);
}
pause(): void {
if (this.paused) return;
this.paused = true;
this.pausedAt = performance.now();
cancelAnimationFrame(this.rafId);
}
resume(): void {
if (!this.paused) return;
this.paused = false;
this.startAt += performance.now() - this.pausedAt;
this.play();
}
private apply(elapsed: number): void {
for (const track of this.config.tracks) {
const el = this.resolve(track.id);
if (!el) continue;
const local = elapsed - track.start;
if (local < 0) {
el.style.opacity = '0';
continue;
}
const raw = Math.min(local / track.duration, 1);
const t = (EASING[track.easing ?? 'linear'])(raw);
for (const prop of Object.keys(track.from)) {
const value = track.from[prop] + (track.to[prop] - track.from[prop]) * t;
if (prop === 'opacity') {
el.style.opacity = String(value);
} else if (prop === 'scale') {
el.style.transform = `scale(${value})`;
} else if (prop === 'y') {
el.style.transform = `translateY(${value}px)`;
}
}
}
}
}
这里有一个性能细节:apply 每帧遍历所有 track,并在循环里写 style,会触发多次样式重算。轨道数量在十条以内问题不大,超过二十条建议先合并计算,再一次性写入 transform,避免同一帧内重复修改同一元素的多个样式属性。
3.3 降级策略要写进播放器本身
降级不能靠调用方自觉,要内置在播放器里。常见的三种情况:
| 场景 | 判断方式 | 降级动作 |
|---|---|---|
| 用户开启减少动效 | matchMedia('(prefers-reduced-motion: reduce)') |
直接跳到时间轴末尾状态 |
| 低端设备 | 设备内存或历史帧率采样低于阈值 | 帧率降到 30,关闭装饰轨道 |
| 页面切到后台 | document.visibilitychange |
暂停播放,回到前台时从断点继续 |
ts复制export function shouldReduceMotion(): boolean {
return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
}
export function attachVisibilityGuard(player: TimelinePlayer): () => void {
const handler = () => {
if (document.hidden) player.pause();
else player.resume();
};
document.addEventListener('visibilitychange', handler);
return () => document.removeEventListener('visibilitychange', handler);
}
prefers-reduced-motion 这一点经常被忽略。它不只是无障碍要求,很多用户在系统里开启省电或减少动态效果后,页面上的大幅位移会引起明显不适。直接跳到结束态既满足需求,也省掉了动画开销。
3.4 一个常见的错误写法
在项目里经常看到这种实现:
ts复制// 不推荐:用固定增量推进
let progress = 0;
function loop() {
progress += 0.016;
render(progress);
requestAnimationFrame(loop);
}
问题在于每帧固定加 16 ms,一旦设备掉帧,动画总时长会从 3.2 秒变成 5 秒甚至更久,和音效完全对不上。推荐用 performance.now() 计算真实经过时间,掉帧只会让画面跳跃,不会让节奏变慢。
4. 素材加载与首屏优化:把等待时间藏进动画里
联动活动页的加载体验好坏,很大程度取决于“等待”被安排在哪里。理想状态是:用户打开页面立刻看到背景和占位主体,动画开始播放的这几秒里,其余素材在后台补齐,动画结束时按钮已经可点。这需要一套有优先级、有并发控制、有失败兜底的加载器。
4.1 带并发上限的预加载队列
浏览器的并发连接数是有限的,一次性发起几十个图片请求,反而会让关键素材排在队尾。加载器要限制并发,并按优先级排序。
ts复制// src/core/loader.ts
export interface AssetItem {
key: string;
src: string;
bytes: number;
}
export interface LoaderOptions {
concurrency: number;
timeout: number;
retry: number;
onProgress?: (loaded: number, total: number) => void;
}
const DEFAULT_OPTIONS: LoaderOptions = {
concurrency: 6,
timeout: 8000,
retry: 2,
};
export class AssetLoader {
private cache = new Map<string, HTMLImageElement>();
private opts: LoaderOptions;
constructor(opts: Partial<LoaderOptions> = {}) {
this.opts = { ...DEFAULT_OPTIONS, ...opts };
}
async loadAll(items: AssetItem[]): Promise<{ ok: AssetItem[]; failed: AssetItem[] }> {
const queue = [...items].sort((a, b) => a.bytes - b.bytes);
const ok: AssetItem[] = [];
const failed: AssetItem[] = [];
let loaded = 0;
const worker = async () => {
while (queue.length) {
const item = queue.shift();
if (!item) break;
try {
const img = await this.loadOne(item.src, this.opts.retry);
this.cache.set(item.key, img);
ok.push(item);
} catch {
failed.push(item);
} finally {
loaded += 1;
this.opts.onProgress?.(loaded, items.length);
}
}
};
await Promise.all(Array.from({ length: this.opts.concurrency }, worker));
return { ok, failed };
}
private loadOne(src: string, retry: number): Promise<HTMLImageElement> {
return new Promise((resolve, reject) => {
const attempt = (left: number) => {
const img = new Image();
const timer = setTimeout(() => {
img.src = '';
if (left > 0) attempt(left - 1);
else reject(new Error('timeout'));
}, this.opts.timeout);
img.onload = () => {
clearTimeout(timer);
resolve(img);
};
img.onerror = () => {
clearTimeout(timer);
if (left > 0) attempt(left - 1);
else reject(new Error('load failed'));
};
img.src = src;
};
attempt(retry);
});
}
get(key: string): HTMLImageElement | undefined {
return this.cache.get(key);
}
}
这段代码有两个关键点值得说明。第一,队列按体积升序处理,小图先完成,视觉上更快出现内容;第二,超时后把 img.src 置空再重试,可以避免旧请求的回调覆盖新请求的状态。
参数的实际影响如下:
| 参数 | 常见值 | 调大的影响 | 调小的影响 |
|---|---|---|---|
| concurrency | 4 到 8 | 并发高,弱网下更容易互相抢占带宽,关键图可能变慢 | 队列变长,总耗时增加 |
| timeout | 6000 到 10000 ms | 慢网下成功率提高,但失败感知变慢 | 弱网用户频繁触发重试 |
| retry | 1 到 2 | 提升成功率,极端情况下放大请求量 | 一次抖动就降级 |
4.2 图片解码要主动控制
图片 onload 只代表下载完成,不代表可以立刻绘制。首次绘制时如果浏览器还在解码,就会出现一整帧的卡顿,在移动端特别明显。现代浏览器提供了 decode() 接口,可以提前解码。
ts复制async function warmDecode(img: HTMLImageElement): Promise<void> {
if ('decode' in img) {
try {
await img.decode();
return;
} catch {
// decode 失败不阻断流程,退回普通绘制
}
}
// 兜底:对于不支持 decode 的环境,用离屏绘制触发一次
const canvas = document.createElement('canvas');
canvas.width = 1;
canvas.height = 1;
canvas.getContext('2d')?.drawImage(img, 0, 0, 1, 1);
}
在一个真实的联动活动页样本里,仅加入预解码这一步,低端安卓机上的首帧卡顿从 200 ms 以上降到 50 ms 以内。这个收益来自把解码成本从“渲染关键帧时”挪到了“空闲等待时”。
4.3 失败兜底与视觉占位
任何素材都可能加载失败。关键组的失败必须重试,交互组的失败可以降级为纯色块,装饰组的失败直接跳过。降级时要保证布局不塌,所以占位元素必须提前定好尺寸。
css复制/* 占位策略:用 aspect-ratio 固定版位,避免图片到达后引起重排 */
.visual-slot {
width: 100%;
aspect-ratio: 3 / 4;
background: linear-gradient(180deg, #1b1b1f 0%, #2b2620 100%);
display: flex;
align-items: center;
justify-content: center;
overflow: hidden;
}
.visual-slot img {
width: 100%;
height: 100%;
object-fit: cover;
opacity: 0;
transition: opacity 240ms linear;
}
.visual-slot img.is-ready {
opacity: 1;
}
aspect-ratio 解决的是老问题:图片加载前高度为 0,加载后撑开页面导致内容跳动。固定比例后,图片到达只是淡入,不会引起布局位移。
4.4 网络质量自适应
不是所有用户都在 Wi-Fi 下。可以用 navigator.connection 做一次粗判断,决定是否加载装饰组。
ts复制type NetworkInfo = { effectiveType?: string; saveData?: boolean };
export function shouldLoadDecor(): boolean {
const conn = (navigator as Navigator & { connection?: NetworkInfo }).connection;
if (!conn) return true;
if (conn.saveData) return false;
return conn.effectiveType === '4g' || conn.effectiveType === 'wifi';
}
这个判断只能作为参考,不能作为唯一依据,因为部分 WebView 不提供该接口。接口缺失时默认加载,是更稳妥的选择。
注意:降级方案必须在开发阶段就能手动触发验证,比如通过 URL 参数强制走降级分支。等到线上才发现降级代码有 bug,是最难处理的情况。
5. 倒计时与活动状态:时间逻辑必须和界面解耦
联动活动页几乎都带倒计时。看似简单,实际是最容易出错的部分:用户改系统时间导致显示错乱、页面长时间挂在后台回来后倒计时停在原地、活动结束瞬间按钮仍然是可点状态。这些问题的根源在于把“当前时间”和“界面状态”混在一起写。
5.1 用服务端时间做基准
判断活动是否开始、是否结束,绝对不能用客户端本地时间。正确做法是页面加载时从服务端拿到当前时间,计算与本地时钟的偏移,之后所有判断都基于“本地时间 + 偏移”。
ts复制// src/core/clock.ts
let offset = 0;
let synced = false;
export async function syncServerTime(endpoint: string): Promise<void> {
const t0 = Date.now();
const res = await fetch(endpoint, { cache: 'no-store' });
const t1 = Date.now();
const data = (await res.json()) as { serverTime: number };
const rtt = t1 - t0;
// 假设请求与响应耗时相近,用一半 RTT 修正
offset = data.serverTime + rtt / 2 - t1;
synced = true;
}
export function now(): number {
return Date.now() + offset;
}
export function isSynced(): boolean {
return synced;
}
这里用一半 RTT 做修正,是一个常见近似。在网络对称的情况下误差很小,弱网下可能有几百毫秒偏差。对于活动开启这种秒级敏感场景,偏差可以接受,但不能省略修正——直接用响应时间会导致系统性偏慢。
还需要注意接口本身要禁用缓存,否则拿到的是上一次的时间。
5.2 状态机比 if-else 更可靠
活动页至少有三个状态:未开始、进行中、已结束。用状态机管理,可以避免多处判断不一致。
ts复制export type Phase = 'loading' | 'pending' | 'active' | 'ended';
export interface PhaseRange {
startAt: number;
endAt: number;
}
export function resolvePhase(range: PhaseRange, current: number, synced: boolean): Phase {
if (!synced) return 'loading';
if (current < range.startAt) return 'pending';
if (current >= range.endAt) return 'ended';
return 'active';
}
界面层只订阅状态变化,不做时间比较。这样即使后续增加了“预约期”“返场期”,改动也集中在状态机里。
ts复制export class PhaseWatcher {
private timer = 0;
private last: Phase | null = null;
constructor(
private range: PhaseRange,
private onChange: (phase: Phase) => void,
private interval = 1000,
) {}
start(): void {
const tick = () => {
const phase = resolvePhase(this.range, now(), isSynced());
if (phase !== this.last) {
this.last = phase;
this.onChange(phase);
}
};
tick();
this.timer = window.setInterval(tick, this.interval);
}
stop(): void {
clearInterval(this.timer);
}
}
5.3 三个必须处理的边界
第一,页面长时间在后台。浏览器会节流定时器,setInterval 可能几分钟才执行一次。解决方案是监听 visibilitychange,回到前台时立即手动执行一次 tick,而不是等下一次定时器。
第二,活动结束瞬间的交互。状态从 active 切到 ended 时,必须同时禁用按钮、清除已提交的请求回调、停止轮询。只改文案而没禁用按钮,会出现用户点击后接口返回错误的情况,体验很差。
第三,跨天与本地时区。服务端时间通常是 UTC 时间戳,格式化展示时要显式指定时区,不要依赖 new Date().toLocaleString() 的默认行为,否则不同设备上的显示可能不一致。
ts复制export function formatRemain(ms: number): string {
const total = Math.max(0, Math.floor(ms / 1000));
const d = Math.floor(total / 86400);
const h = Math.floor((total % 86400) / 3600);
const m = Math.floor((total % 3600) / 60);
const s = total % 60;
const pad = (n: number) => String(n).padStart(2, '0');
return d > 0 ? `${d}天 ${pad(h)}:${pad(m)}:${pad(s)}` : `${pad(h)}:${pad(m)}:${pad(s)}`;
}
用 Math.max(0, ...) 防御负值,是很小但很必要的一步。少了它,活动结束后页面上会出现 -1天 23:59:59 这样的显示。
5.4 时间接口本身的稳定性
倒计时依赖服务端时间接口,这个接口必须比活动接口更早可用。工程上建议把它做成静态化的轻量接口,返回极简 JSON,并且设置较短的超时。如果时间同步失败,页面应该进入“加载中”而不是随便用本地时间顶上。
ts复制export async function syncWithFallback(endpoint: string, retries = 2): Promise<boolean> {
for (let i = 0; i <= retries; i += 1) {
try {
await syncServerTime(endpoint);
return true;
} catch {
await new Promise(r => setTimeout(r, 300 * (i + 1)));
}
}
return false;
}
失败时给出明确的“网络异常,请刷新重试”提示,比让用户看到一个不准的倒计时更好。倒计时一旦不准,用户会认为整个活动不可信。
6. 运行验证与真机排查:从白屏到掉帧的定位链路
页面在开发机上跑通只是开始。联动活动页的绝大多数问题只在真机上出现,而且往往集中在活动开启的那几分钟。排查必须按链路走,而不是靠反复刷新碰运气。
6.1 白屏的三层排查顺序
白屏是最常见的故障现象,可能原因分布在完全不同的层次。按下面的顺序查,能最快缩小范围。
第一层,资源是否到达。打开 network 面板,看 HTML 本身是否 200。如果 HTML 是 404,问题在部署路径或者 base 配置。
第二层,脚本是否执行。如果 HTML 正常但页面空白,检查控制台是否有语法错误。低级浏览器不支持 ?. 或 ?? 时,整包脚本会直接失败。这就是构建目标要设成 es2018 的原因。
第三层,渲染是否被遮挡。脚本执行正常但仍看不到内容,检查是否存在一个全屏遮罩层因为动画没触发而停留在 opacity: 1。这类问题在时间轴动画里很典型:时间轴因为某个异常提前退出,遮罩永远不会淡出。
对应的检查命令和要点:
| 现象 | 优先检查 | 具体动作 |
|---|---|---|
| HTML 返回 404 | 部署路径 | 对比 base 与实际目录,确认 index.html 位于正确层级 |
| 控制台语法错误 | 浏览器版本与构建目标 | 用目标机型 UA 检查,降低 build.target |
| 内容被遮罩 | 时间轴是否执行完 | 在 onDone 里打点,确认回调被调用 |
| 只有背景没有主体 | 关键组图片请求 | network 过滤图片,检查是否 403 或超时 |
6.2 掉帧的定位方法
帧率问题不能靠感觉。在页面里内置一个轻量采样器,开发阶段通过 URL 参数打开,生产环境默认关闭。
ts复制export function startFpsProbe(onReport: (stats: { avg: number; slowRatio: number }) => void, duration = 3000) {
const gaps: number[] = [];
let last = performance.now();
let raf = 0;
const loop = (now: number) => {
gaps.push(now - last);
last = now;
if (now - (gaps[0] ?? now) < duration) {
raf = requestAnimationFrame(loop);
return;
}
const avg = 1000 / (gaps.reduce((a, b) => a + b, 0) / gaps.length);
const slowRatio = gaps.filter(g => g > 33).length / gaps.length;
onReport({ avg: Math.round(avg), slowRatio: Number(slowRatio.toFixed(3)) });
};
raf = requestAnimationFrame(loop);
return () => cancelAnimationFrame(raf);
}
拿到数据后按可能性排序排查:
slowRatio高且集中在动画开始阶段,多半是图片解码或大量 DOM 写入。slowRatio高且贯穿全程,检查是否有持续的重排,比如每帧读取offsetWidth。- 只有特定机型掉帧,优先怀疑大尺寸图层合成和阴影效果。
真机上还有一个隐蔽问题:部分 WebView 对 filter: blur() 和 box-shadow 的合成开销极高。联动主题常做发光效果,如果大面积使用模糊,帧率会明显下降。替代方案是预渲染一张模糊图,或者改用低透明度的径向渐变。
6.3 常见问题速查表
下面这张表覆盖了这类页面最常见的问题,可以作为上线前的自检项。
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 首屏图片闪一下才出现 | 未设置占位比例 | 观察加载过程 | 用 aspect-ratio 固定版位并淡入 |
| 动画和音效不同步 | 音效独立播放,未挂到时间轴 | 对比时间轴日志 | 把音效触发点写入 timeline |
| 倒计时在后台回来后停滞 | 定时器被节流 | 切后台 5 分钟后返回 | 监听 visibilitychange 立即补一次 |
| 部分机型字体错乱 | 字体子集缺失或未 font-display |
换机型对比 | 设置 font-display: swap 并补全字符集 |
| 点击按钮无反应 | 遮罩层未移除或状态未切换 | 检查 pointer-events 与状态 |
状态切换时同步清理遮罩 |
| 二次进入页面白屏 | Service Worker 缓存了旧 HTML | 清缓存后对比 | 给 HTML 设置不缓存,静态资源用指纹 |
6.4 学习环境与真机环境的差异验证
本地开发时,建议至少做三项模拟:用浏览器开发者工具把网络限速到 Fast 3G,把 CPU 降速 4 倍,把页面切到后台再切回来。这三项能覆盖大部分弱网和低端机的表现。
真机验证则要覆盖:目标平台的内置浏览器(不同版本)、iOS Safari、主流安卓机型各一台低端和一台中端。验证内容不只是“能不能看”,而是按清单逐项确认:
- 首屏是否在可接受时间内出现主体。
- 动画是否完整播放到结束。
- 倒计时是否与服务端时间一致。
- 点击主按钮是否进入正确状态。
- 断网后是否有明确提示。
注意:验证要在真实的发布路径下进行,而不是本地 dev server。路径、缓存头、CDN 行为在两者之间往往不同。
7. 生产环境还需要补上的稳定性与合规能力
学习环境跑通之后,距离可以发布还有一段距离。联动活动页生命周期短、流量尖峰明显,出问题的窗口很小,所以监控、发布和回滚必须提前准备好,不能等到出事再补。
7.1 埋点要围绕可诊断设计
活动页的埋点不是只统计 PV。真正有用的是能定位问题的数据。建议至少采集以下几类:
| 事件 | 关键字段 | 用途 |
|---|---|---|
| page_ready | 首屏时间、网络类型、UA | 评估首屏表现分布 |
| asset_fail | 资源 key、重试次数、耗时 | 定位具体素材的失败率 |
| timeline_end | 实际总时长、是否降级 | 判断动画是否按预期播放 |
| phase_change | 前后状态、服务端时间偏移 | 排查倒计时异常 |
| click_cta | 当前状态、是否成功 | 分析交互失败原因 |
上报要做采样和批量发送。活动开启时并发很高,逐条上报会给日志服务带来额外压力;同时上报逻辑本身不能阻塞主流程,失败要静默处理。
ts复制const buffer: unknown[] = [];
export function track(event: string, payload: Record<string, unknown>): void {
buffer.push({ event, ts: Date.now(), ...payload });
if (buffer.length >= 20) flush();
}
function flush(): void {
if (!buffer.length) return;
const body = JSON.stringify(buffer.splice(0, buffer.length));
navigator.sendBeacon?.('/api/log', body);
}
使用 sendBeacon 是为了在页面关闭时也能把数据发出,普通 fetch 在卸载阶段可能被中断。
7.2 发布策略与回滚通道
联动活动页的发布有几个硬要求:
- HTML 入口不缓存或设置极短缓存,静态资源带内容指纹并设置长缓存。
- 灰度发布,先放小比例流量观察首屏时间和错误率,再逐步放量。
- 保留上一版本的完整静态包,回滚时只切入口指向。
- 素材与代码版本绑定,避免出现“新代码配旧素材”的组合。
回滚要能在分钟级完成。实际做法是把整个活动页构建产物打成带版本号的目录,入口通过配置指向当前版本,回滚只改配置。这个机制在活动开启前必须演练过一次。
7.3 素材使用的合规要点
联动主题涉及第三方版权,工程上有几点必须落到 checklist 里:
- 素材域名限制在授权范围内,不随意分发到其他站点。
- 图片开启防盗链,避免被外部页面直接引用。
- 活动结束后按约定下线素材,入口返回说明页而不是继续展示。
- 不在前端代码里硬编码与授权无关的内部信息。
这些不是技术难点,但漏掉会造成实际麻烦,值得在发布前逐条核对。
7.4 上线前可复用检查清单
下面这份清单可以直接拿去用,建议在发布前逐项打勾,而不是凭记忆确认。
环境与构建:
- 构建产物的
base与实际部署路径一致。 - 静态资源文件名带指纹,HTML 入口不缓存。
- 构建目标覆盖目标机型的最低浏览器版本。
- 素材清单由脚本生成,未手工修改。
功能与状态:
- 倒计时基于服务端时间,接口禁用缓存。
- 三种状态(未开始、进行中、已结束)都验证过界面表现。
- 结束后按钮禁用且提示明确。
- 页面从后台返回时倒计时立即刷新。
性能与降级:
- 首屏关键组素材总体积在预算内。
- 开启减少动效后页面仍可正常使用。
- 弱网与低端机下装饰组可跳过。
- 关键素材失败时有重试与占位。
监控与运维:
- 首屏时间、资源失败、状态切换均有埋点。
- 上报不阻塞主流程,页面关闭时可发出。
- 上一版本静态包保留,回滚路径已演练。
- 活动结束后的下线方案已确认。
8. 从这次联动主题延伸出的通用做法
把《第五人格》与《九色鹿》这类联动主题做成一个能稳定上线的页面,真正沉淀下来的不是某段动画代码,而是三件事:素材分层与清单化、时间轴数据驱动、状态与时间解耦。这三点在任何带视觉叙事的活动页里都适用,换成其他主题也只是替换素材和配置。
如果要在现有基础上继续深入,有三个方向值得投入。第一,把时间轴配置抽成可视化编辑工具,让美术或运营能直接调节奏并导出 JSON,减少前后端来回沟通。第二,把预加载器和降级策略封装成团队内的公共包,下一个活动页直接复用,避免每次都重新踩一遍并发和超时的坑。第三,把真机性能采样做成常态化能力,每次发布前自动跑一遍目标机型,把帧率和首屏时间纳入发布门禁。
对刚接触这类页面的开发者,最值得练的是一次完整的“从素材到上线”流程:自己准备十张左右的图片,写一份时间轴配置,实现加载队列和倒计时,然后在限速和降 CPU 的条件下跑一遍,把遇到的问题记下来。这个过程比看十篇文章更能建立对活动页工程复杂度的直觉。联动主题的视觉可以很复杂,但支撑它的工程结构应该尽量简单、可预测、可验证。
