很多做 CocosCreator H5 游戏的同学，第一次打包上线，都会盯着那个默认的 Cocos logo 加载画面发愁。你说它难看吧倒也谈不上，但就是一股“引擎默认味”，跟游戏本身的调性完全不在一个频道。而且一旦你的首包做得比较大，这个默认画面还要停留两三秒，配上一个几乎没人看得懂的加载百分比，玩家还没进游戏就想退出了。今天这篇就把我自己项目里给 CocosCreator 定制 H5 启动页的完整方案整理出来，包括核心原理、模板修改、进度条处理和几个我踩过 N 次的坑。不管你是刚接触引擎的新手，还是已经上线过几个小游戏的在职开发，这套思路都能直接用。
启动页这事看起来就是“换一张图、加一个动画”，但真做起来牵扯到浏览器加载机制、引擎初始化时序、资源分包策略，甚至还和音频自动播放限制有关。网上能搜到的资料大多只告诉你“改 index.ejs 里的那个 div”，但很少有人讲清楚为什么改完之后还是会闪白屏、进度条为什么卡在 99%、微信里为什么不播放声音。这篇就把这些底层逻辑一并补齐。
1. 自定义启动页的核心逻辑：先搞懂浏览器和引擎之间的接力赛
1.1 引擎加载 H5 项目的真实流程
想改启动页，第一件事是搞清楚一个 H5 游戏从玩家点开链接到看到游戏画面，中间到底发生了什么。这个流程看起来是瞬间完成，实际拆开看是一条很长的链条。
用户在浏览器里输入地址之后，浏览器第一步是下载index.html，这个文件体积不大，但它是整场接力赛的第一棒。拿到 HTML 之后浏览器开始解析 DOM，同时发现里面有<script>标签，于是开始下载并执行引擎脚本。CocosCreator 打包出来的引擎脚本可不小，压缩之后也有几百 KB 甚至更大，在弱网环境下光这一步就要等一两秒。引擎脚本执行完之后，底层渲染系统初始化，接着下载首包资源——也就是第一个场景相关的场景文件、图片、音频、json 配置这些。首包资源下载并解析完毕，引擎才开始真正跑游戏逻辑，把画面渲染到页面上那个<canvas>元素里。
重点来了：在你看到 canvas 画面之前，页面上唯一能显示内容的地方，就是 HTML DOM。如果你不往 HTML 里塞任何自定义内容，玩家看到的要么是白屏，要么是引擎默认的那个加载界面。CocosCreator 默认模板里面其实是有加载框的，只是它长得很“工程化”——一个居中的轻量动画或者一段纯文本，跟游戏美术风格完全不搭。我们做自定义启动页，本质上就是抓住这个从“HTML 解析完成”到“引擎渲染第一帧”之间的时间窗口，把自己的 Logo、进度条、提示文案塞进去，然后在合适的时机再把它移除。
这里要提一个新手很容易犯的认知错误：以为启动页是在 CocosCreator 场景里做的。你确实可以在第一个场景里做一张全屏 sprite 当启动页，但那样做有一个天然缺陷——首包资源没下载完之前，引擎根本没法渲染第一帧，所以你那个“启动页”反而变成了最晚出现的东西。真正的加载等待期，依然只能靠 DOM 层去兜。所以 H5 项目的自定义启动页，正解就是写在 HTML 模板里。
1.2 两种主流实现思路的取舍
除了改 DOM 模板，确实也存在“引擎场景内做启动页”这种路线。我团队早期一个项目就是用的这个方案：建一个 Launch 场景，放上 logo 和进度条 UI，然后脚本里监听资源加载进度，用cc.director.loadScene切到下一个真实场景。这个方案在原生平台跑得挺好，因为原生平台的启动图和场景切换是无缝衔接的。但放到 H5 上就出问题了——首包资源不加载完，Launch 场景自己都出不来。最终效果就是页面先白屏一会儿，突然弹出一个启动页，然后又突然消失。这个“白屏”阶段恰恰是玩家流失最严重的地方。
改模板的做法则是把启动页做在 HTML/CSS/JS 层，跟引擎完全解耦。页面一打开，启动页 DOM 立刻出现，不管引擎脚本多大、首包资源多慢，启动页都能稳定展示。引擎那边准备就绪之后，通过全局变量或者事件回调通知 HTML 层把启动页移除。这个方案的优点就是首屏极快、视觉一致性高、可控性强，缺点也很明显——只能用在 Web 平台，微信小游戏或者其他原生平台没法复用。如果你项目主要面向 H5，那这个取舍基本不用犹豫，直接走模板方案。
另外还有一种进阶思路，就是在模板方案的基础上，把“点击进入”按钮也做进去，让玩家主动触发音频播放。这个后面在坑位里详细展开。
2. 起步准备：模板目录、素材与构建配置
2.1 找到 build-templates 模板目录
老版本 CocosCreator（2.x）和 3.x 的模板目录有些差别。2.x 一般在项目根目录下有一个template文件夹，里面分web-mobile和web-desktop，对应的构建平台不同，入口文件就是index.ejs。3.x 用的名字则是build-templates，结构差不多，同样是web-mobile/index.ejs。
如果你项目里没有这个目录，别慌，手动新建就行。CocosCreator 构建的时候会优先读取这个目录下的模板文件来生成最终的index.html。没有模板文件，就用引擎内置的默认模板。这个目录名不要拼错，构建平台也记得选对——我做 H5 基本只改web-mobile，web-desktop是给 PC 浏览器用的，两套模板可以独立维护。
还有一条非常重要：不要直接去改构建输出目录里的 index.html。很多人图省事，直接在build/web-mobile/index.html里改，当时确实生效了，但下一次构建，所有改动会被全部覆盖。模板文件是源头，改模板，构建产物自动跟着变。
2.2 准备自定义启动页的素材与 UI 结构
启动页需要哪些素材，取决于你想做到什么程度。最基础的就是一张 Logo 图和一个进度条。Logo 格式建议用 PNG，如果设计师能出 SVG 更好——体积小、缩放不受分辨率影响。但用 SVG 时要注意：如果你准备把 CSS 和图片全部内联到单文件模板里，SVG 会额外增加转义难度，直接用 PNG 反而是最省心的。尺寸上，800x600 左右的 logo 图就够用，太大没必要，启动页停留时间本来就短，玩家不会凑近看细节。
UI 结构上，我常用的布局是三层：最底层一个全屏背景（纯色或渐变），中间放 Logo 和一句 Slogan，底部一条细进度条。有些休闲游戏还会加一行“加载中，请稍候…”的文案，以及一个转圈动画。这些都是 CSS 就能搞定的事，不需要额外做图片资源。
还有一点要提前想好：启动页上要不要放“点击进入”按钮。如果游戏场景中有音频需求，强烈建议加一个。原因后面讲音频坑的时候会细说。按钮的素材同样可以纯 CSS 实现，比如一个圆角矩形加文字，比图片灵活得多。
2.3 构建配置里需要留意的选项
在 CocosCreator 构建面板里，有几个选项会直接影响启动页方案的效果，构建之前最好先过一遍。
第一个是“内联所有脚本”。H5 构建时，引擎脚本和项目代码可以内联到index.html里，也可以拆成独立 js 文件。两者对启动页逻辑没本质影响，但内联会让文件体积变大、首字节加载变慢，拆分会多几次请求。我的建议是保持默认，启动页代码只判断window.cc是否存在，不管内联还是外链都适用。
第二个跟分包有关。如果项目里有配置远程包或者子包，构建出来的资源会区分“首包”和“后续包”。首包越小，启动页停留时间越短。这一点直接影响用户体验——启动页做得再漂亮，首包 5MB 照样留不住人。好的实践是首包只放启动场景、核心 UI 和初始配置，其余资源全部挂远程包。
第三个是物理引擎和模块裁剪。CocosCreator 构建时可以选择裁掉没用的引擎模块，比如你的游戏不用物理，就把物理模块去掉，引擎脚本体积能缩不少。引擎体积小了，启动页等待时间自然缩短。
3. 实操：从 index.ejs 注入自定义启动页
3.1 修改模板文件的第一步
找到index.ejs之后，用任意文本编辑器打开。它本身就是一个 HTML 文件，只是里面嵌了一些 EJS 模板变量，构建时 CocosCreator 会把这些变量替换成真实数据。我们的目标很明确：在<body>的最前面插入一段自定义启动页的 HTML 结构。
之所以要放在<body>最前面，是因为浏览器解析 HTML 是按顺序来的，越靠前的 DOM 越早被绘制。CocosCreator 默认生成的启动 loading 内容一般挂在后面，我们自己的启动页放在前面，能确保第一时间出现在屏幕上。
下面这段是我项目里常用的基础结构，你可以直接参考：
<body> <div id="splash" class="splash"> <div class="splash__inner"> <img class="splash__logo" src="logo.png" alt="logo" /> <p class="splash__slogan">REAL-TIME COMBAT BEGINS</p> <div class="splash__progress"> <div class="splash__progress-bar" id="splashProgressBar"></div> </div> </div> </div> <!-- 引擎生成的 canvas 会追加到这里 --> <canvas id="GameCanvas"></canvas> <!-- 引擎脚本 --> <script src="main.js"></script> </body>注意src="logo.png"这里的资源路径。如果你只是把 Logo 图片放在项目根目录某个地方，构建之后它不会自动出现在构建产物里。最稳妥的方式是把图片放在build-templates/web-mobile目录下，构建的时候模板目录里的静态资源会被一并拷贝到输出目录，路径直接用相对路径引用即可。
3.2 CSS 布局与屏幕适配细节
启动页布局最核心的一个点：全屏覆盖。不管设备是刘海屏、挖孔屏还是普通 16:9，都要保证启动页能把整个可视区域盖住，还要保证在 canvas 初始化完成前，玩家看不到任何边角露出来的白底。
我的做法是给.splash用position: fixed，并且把四个方向全部定位到 0。不要用position: absolute，因为固定定位是相对视口的，页面即使出现滚动条也能完整覆盖。inset: 0是这四个方向定位的简写，如果你要兼容特别老的浏览器，就老老实实写全四个值。
背景色我习惯用深色系，因为游戏启动页大多以深色背景配发光 logo 为主。渐变背景也可以，但注意不要在启动页上做太复杂的 CSS 动画，尤其是filter和backdrop-filter，低端安卓机上容易掉帧甚至白屏。渐变、透明度、transform 这类属性性能相对友好，可以大胆用。
进度条我用了两个嵌套的 div，外层是灰色的轨道，内层是填充条，宽度用 JS 控制。样式上，轨道可以给一个border-radius做成圆角，填充条加个transition: width 0.3s ease，这样每次宽度更新时进度条会有平滑的滑动效果，视觉上比突跳自然得多。
3.3 进度条与引擎就绪回调：如何判断“引擎已经准备好”
启动页能不能顺利收场，关键在“什么时候隐藏它”。判断过早，引擎还没接管 canvas，会闪一下白屏；判断过晚，玩家要盯着启动页多看好几秒，同样难受。
市面上最稳的判断方式其实不是 Cocos 官方文档里写的某个事件回调，而是一个简单的轮询——每隔 100ms 检查一次全局对象是否就绪。H5 构建之后，Cocos 引擎脚本会把核心 API 挂到window.cc上。只要cc.game和cc.director存在，基本可以认为引擎核心已经初始化完成。
下面这段是我实际项目里用过的隐藏逻辑，注释里写了关键节点的作用：
(function () { var splash = document.getElementById('splash'); var bar = document.getElementById('splashProgressBar'); var minShowTime = 1200; // 最小展示时间，防止启动页一闪而过 var startTime = Date.now(); var timer = null; function setProgress(value) { if (bar) { bar.style.width = (value * 100) + '%'; } } function finishSplash() { var elapsed = Date.now() - startTime; var remain = Math.max(0, minShowTime - elapsed); setTimeout(function () { if (bar) bar.style.width = '100%'; setTimeout(function () { if (!splash) return; splash.classList.add('splash--hidden'); setTimeout(function () { if (splash && splash.parentNode) { splash.parentNode.removeChild(splash); } }, 500); }, 200); }, remain); } timer = setInterval(function () { // 这里用时间做参考，让进度条在 6 秒内平缓升到 80% 左右 var elapsed = Date.now() - startTime; var rate = Math.min(1, elapsed / 6000); setProgress(0.8 * rate + 0.05 * Math.random()); if (window.cc && cc.game && cc.director) { window.clearInterval(timer); finishSplash(); } }, 100); })();这段代码的思路是：引擎没就绪时，进度条走一条时间曲线，大概 6 秒涨到 80%，不要让玩家干等看不到反馈；一旦检测到cc.director存在，就走finishSplash，补足最小展示时间，把进度条拉到 100%，再做淡出动画移除启动页。
使用轮询而不是引擎事件，是为了兼容性。Canvas 构建版本在不同项目里事件名有差异，轮询只要判断对象存在性即可，稳定且无脑。
3.4 最小展示时间与淡出动画的细节处理
很多 H5 游戏在快速网络下，引擎可能一两秒就加载完了。如果引擎一就绪立刻隐藏启动页，玩家只看到一个残影，启动页等于白做。所以我在代码里加了一个minShowTime变量，强制启动页至少展示 1.2 秒。这个数值不是拍脑袋定的，是我试了几个档位之后觉得最舒服的值——太短没有记忆点，超过 2 秒又会让玩家不耐烦。具体你可以根据自己启动页的信息量调整，含 logo 品牌信息多一点可以放到 1.5 秒。
淡出动画我也用了两段式：先把进度条拉到 100%，停顿 200ms，让玩家看到“加载完成”的状态，然后再执行整个.splash容器的透明度过渡动画。过渡时长 500ms 配合 CSS 的transition，最终效果是启动页柔和消失，而不是突然消失。
这里有个很容易被忽略的点：启动页移除时不要用display: none直接给它消失。因为display无法参与过渡动画，玩家看到的会是一个瞬间跳变的切场。正确做法是调 opacity 到 0，等transitionend或者直接 setTimeout 之后再真正从 DOM 里移除。如果你嫌麻烦，用visibility: hidden过渡配合也一样。
4. 进度条到底要不要绑定真实加载进度
4.1 H5 资源加载进度的获取方式
在做启动页的过程中，有一个问题一定会遇到：进度条到底显示真实的资源加载进度，还是自己模拟一个？
从能力上讲，Cocos 引擎确实给了获取进度的接口。早年 2.x 用cc.loader.onProgress，3.x 的assetManager也支持监听单个 bundle 的加载进度。如果你只是显示首包资源加载了多少，可以这么做：拿到config.json里声明的资源总数量，监听已加载数。但实际操作中，这个“真实进度”的体验并不好。原因有三点：
第一，H5 的资源加载受浏览器并发连接数限制，进度不是线性的。很多时候总进度在 0% 的时候卡好几秒，然后突然蹿到 90%，这种进度条给玩家的心理暗示反而更差。
第二，分包机制会让“总进度”变得很难算。远程包可能没被算进首包进度里，但玩家能感知到点击“开始”之后又有等待。
第三，也是最重要的一点：Cocos 自身在首包加载之外还有引擎脚本下载、编译执行、着色器初始化等步骤，这些统统不算资源下载进度，但对于“玩家看到画面”这件事来说是实打实的等待时间。
所以我最后选择了“模拟进度 + 真实完成事件”的混合方案。进度条展示的是预估等待曲线，引擎真正就绪时才做完成态。这个方案实现起来简单，而且只要参数调得好，玩家感知不出来和真实进度有什么区别。
4.2 模拟进度的常见策略与兜底逻辑
模拟进度在设计上有一条铁律：永远不要一眼假。如果启动页显示 0% 持续两秒，然后突然跳 50%，玩家会觉得“卡住了”。好的模拟策略是让进度条前期走得快一点、中期变缓、后期平滑逼近 90%，然后等待完成回调把它拉到 100%。
前面代码里我用的是线性时间曲线，在 6 秒内从 0 走到 80%。实际项目里我会再拆细一点：前 2 秒走到 40%，第 3 到 6 秒只走到 80%，最后 20% 留给完成回调。这个节奏更符合人类对“加载”的心理预期——初始有反馈，中期感觉快完成了，后期要等待确认。
进度条还必须有一个兜底：就算引擎加载时间超过预估，进度条也不能一直停在 80% 不动。正常情况引擎再慢也不该超过 10 秒，超过这个时间说明网络异常或者脚本报错。可以写一个超时分支：如果 12 秒后仍没检测到引擎就绪，把进度条显示到 99%，同时文案改成“连接中，请检查网络”。这个处理虽然不能解决加载失败，但至少不会让玩家面对一个死寂的白屏，降低流失率。
4.3 常见进度条卡住问题的排查
进度条卡住，很多时候原因不在启动页代码本身，而是引擎根本加载失败了。你要是第一次做，遇到这种情况先别怀疑轮询逻辑，打开控制台看一眼有没有红色报错。
最常见的一个是 404——引擎脚本或者资源路径找错了。这个一般和部署目录有关，构建产物放到服务器子目录下，而index.html里用了绝对路径。另一个常见问题是资源跨域，图片、音频、配置文件放在 CDN 上而 CDN 没开 CORS 头，浏览器会直接拦截。排查思路很简单：先用本地服务器跑一遍，用控制台 Network 面板看有没有红色请求，再看截图确认加载的是不是构建产物里的 index.html。我见过好几个项目，改完模板本地预览正常，传到服务器上就白屏，最后发现是只传了资源目录忘了传index.html。
如果进度条到 90% 之后怎么都不动，优先级最高的排查方向是config.json有没有被正确加载。这个文件记录了资源映射关系，如果它加载失败，引擎就算初始化了也无法进入场景。
5. 实操过程中踩过的典型坑
5.1 白屏和闪屏：引擎就绪不等于首帧渲染完成
我在 3.3 里给出的轮询代码有个前提：它判断的是“引擎核心对象存在”，但这并不代表 canvas 上已经画出第一帧画面。如果启动页在这个节点立刻淡出，玩家会看到一个短暂的白屏——引擎初始化完了但第一个场景还没渲染上屏。
这个问题在低端机上尤其明显。好的做法是让场景脚本主动告诉 HTML 层“我真的准备好了”。可以在第一个场景的脚本文本里加一行：
cc.director.on(cc.Director.EVENT_AFTER_SCENE_LAUNCH, function () { try { window.dispatchEvent(new Event('cocos-game-ready')); } catch (e) {} });然后在模板的启动页代码里监听这个事件，收到之后再走finishSplash。轮询只是兜底，事件通知才是准确的。
如果你不想动场景脚本，从启动页角度也有一个补救措施：把隐藏启动页的时机延后到引擎脚本加载完成后的 200~400ms，用 setTimeout 模拟“渲染缓冲”。这个做法实测能缓解大部分白屏，但治标不治本，低端机依然可能闪。
5.2 音频无法自动播放：浏览器策略逼你加一个按钮
你做的 H5 游戏如果有背景音乐，一定会遇到这个坑：在启动页展示阶段，脚本里尝试用AudioContext播放音频，浏览器直接报play() failed because the user didn't interact with the document first。这是浏览器很严格的自动播放策略，不是 Cocos 的限制，也不是你代码写错了。
解决办法只有一个：给用户一个手势交互。最自然的就是在启动页上加一个“点击进入”按钮，把“移除启动页”和“解锁音频”绑定在同一个点击事件里。处理逻辑是先调用一下AudioContext.resume()或者播放一段静音音频，再去隐藏启动页。凡是第一次点击之后，后续所有音效都畅通无阻。
很多休闲游戏还把这个“点击进入”做成了玩法的一部分，比如按钮上写“开始冒险”配一个弹跳动画，既满足浏览器策略，又提升了启动页的仪式感。这个方案强烈推荐，别在启动页阶段硬刚浏览器策略。
5.3 微信内置浏览器兼容性：CSS 别玩太花
H5 游戏在国内传播主要靠微信内置浏览器。这个浏览器基于 X5 内核，整体兼容性还可以，但有一些历史版本对 CSS 特性的支持很迷。我之前在启动页上用了position: fixed配合100vh，在 iOS Safari 和部分安卓微信里出现了高度塌陷问题——底部露出一条白边，特别尴尬。
后来我把高度策略改成了四边定位为 0，不依赖100vh，问题就消失了。此外，微信浏览器里页面字体大小跟随系统设置，如果你启动页文案用了很小的字号，在系统放大字号后可能被截断。如果你希望字体大小不受系统调节影响，可以加一 CSS 规则强制固定，但要注意可访问性的权衡。具体做法因人而异，我这里就不贴代码了。
另外微信内置浏览器对 CSS 动画的硬件加速支持不稳定，尤其是filter: blur()这种比较重的滤镜。启动页上尽量不要用大面积模糊效果，想突出 Logo 就用透明度渐变或者缩放，效果反而干净。
5.4 分包加载场景：大首包会让启动页变长期广告页
如果你的游戏用了远程分包，启动页的“等待感”会再一次升级。首包加载完之后，引擎会立刻去拉远程包，这时候玩家可能已经切到游戏场景里了。如果一个资源下载得很慢，游戏内可能反复触发“等待资源”的遮罩，不如直接把这个阶段也合并进启动页。
实现思路是：在游戏场景脚本里监听远程包下载进度，把事件数据转成 DOM 层的展示。最简单的方式是定义全局变量window.__subpackProgress，启动页轮询读取并更新进度条。做出来效果就是启动页一直显示“正在加载游戏资源 87%”，等资源全部就绪再点击进入。这个设计在商业项目里很常见，比让玩家进去之后被卡在某个节点强太多。
6. 扩展：这套方案能不能用在其他平台
6.1 微信小游戏没有 DOM，怎么做启动屏
微信小游戏环境没有 DOM，HTML 模板方案用不了。小游戏平台有自己的启动屏配置，在游戏加载阶段由微信客户端展示一张图片，这张图在后台管理系统配置，不能动态生成。如果你想在启动屏之后做一个跟品牌一致的“过场动画”，只能在第一个场景里用 Sprite 自己搭，用wx.onShow和wx.getLaunchOptionsSync控制流程。
模板方案里的“模拟进度 + 真实完成事件”这个思路在小游戏平台同样适用，只是承载进度条的载体从 DOM 元素变成了 Canvas 上的 UI 节点。做的时候要注意，Canvas 的启动场景不能被拆分到子包，否则启动场景本身加载就很慢。
6.2 App 内嵌 H5 的启动页注意点
现在很多 App 会在 WebView 里加载 H5 游戏，这种场景下启动页方案基本可用，但有几个 App 环境的细节需要单独处理。一个是 UA 判断，你可能要通过navigator.userAgent识别出 App 的 WebView 环境，决定要不要隐藏启动页里的“浏览器下载提示”之类的按钮；另一个是localStorage，部分 App 的 WebView 可能禁用了 localStorage，如果你在启动页阶段有存储逻辑，要做 try/catch 兜底。
App 内嵌 H5 还会遇到返回键事件拦截问题。安卓端的返回键默认会把 WebView 直接关掉，如果你希望返回键在启动页阶段不生效，需要在模板里监听popstate或者通过 JS 接口调 Native。不过这个已经超出启动页本身了，属于 H5 容器适配，展开讲又是一篇文章，先提一嘴，等真遇到了再回来深挖。
6.3 从启动页延伸到游戏内加载场景的最佳实践
做启动页的过程里你会积累一批关于“加载体验”的经验，这些经验完全可以复用到游戏内部的其他加载场景。比如场景切换时如果资源较多，不要直接黑屏，可以复用一个半透明的加载遮罩，样式和启动页保持同一套视觉语言。再比如进度条，游戏内部的真实加载进度可以直接用assetManager的 onProgress 监听，因为场景内资源加载的总进度是相对可预测的，不需要像启动页那样模拟。
另一个经验是资源缓存策略。启动页本身不参与游戏逻辑，但它出现的时间长短直接受首包体积影响。项目里如果能把核心场景依赖的资源尽量拆小，或者把一些公共资源挂到 CDN 并设置合理的缓存过期时间，二次打开游戏时启动页会明显变短。这个优化比启动页本身做得再花哨都更实在。
最后分享一个我个人的小习惯：每次改完启动页，我都会用性能面板录制一次完整的打开到进入游戏的过程，重点看三个时间点——首页白屏出现、启动页出现、启动页消失。只要这三个时间点的间隔符合预期，启动页的体验基本就稳了。做 H5 自定义启动页，代码量其实很少，真正难的是怎么把每个阶段的衔接做顺。别急着加动画，先把流程跑通，剩下的都是锦上添花。
