游戏引擎 / 系统课时
部署静态网站并回归关键流程
部署静态网站并回归关键流程
游戏在本地开发服务器中正常运行,不代表发布后也能正常工作。静态托管环境可能暴露资源路径、HTTPS、缓存和移动端音频限制等问题。本课使用 Vite 构建 Phaser 4 游戏,将产物部署到 Cloudflare Pages,并通过资源检查与关键玩法回归,完成一次可记录、可复验的 Web 上线验收。
学习目标
- 构建 Phaser 游戏的生产版本,并部署到 HTTPS 静态托管环境。
- 使用浏览器开发者工具验证图片、音频和关卡 JSON 的实际加载情况。
- 按测试用例回归开始、暂停、死亡和结算流程,定位上线后才出现的问题。
构建可发布目录
以下以使用 Vite 构建的 Phaser 4 项目为例。假设项目根目录存在 package.json、package-lock.json,并在 package.json 的 scripts 中配置了 build: vite build。Vite 默认将生产构建产物写入 dist,如果项目修改过 build.outDir,应使用实际输出目录。
在项目根目录执行以下命令。示例适用于已安装 Node.js 和 npm 的环境,使用 Windows PowerShell、macOS Terminal 或 Linux 终端均可执行。
npm ci
npm run build
node -e "const fs = require('node:fs'); if (!fs.existsSync('dist/index.html')) { console.error('BUILD_ARTIFACT_MISSING'); process.exit(1); } console.log('BUILD_ARTIFACT_OK');"预期输出:依赖安装和 Vite 打包日志会随版本、文件数量及构建环境变化,但构建成功后最后一条自定义检查结果应为:
BUILD_ARTIFACT_OKnpm ci 使用锁文件安装依赖,适合重复构建;如果项目没有 package-lock.json,应先使用项目实际采用的包管理器建立并提交锁文件。构建失败时不要部署旧的 dist 目录。
检查 dist/index.html 是否存在,并确认其引用的 JavaScript、CSS 及静态资源已生成。对于 Vite 默认配置,放在 public 目录下的文件会按相对目录结构复制到 dist 根目录,例如 public/levels/level-1.json 对应 dist/levels/level-1.json。
需要区分两种资源路径:通过 JavaScript 导入的资源通常由 Vite 处理构建路径,而 Phaser Loader 中直接书写的 URL 字符串不一定会被 Vite 改写。部署在域名根路径时,默认 base: '/' 通常适用;部署在 /game/ 等子路径时,还要检查 Vite 的 base 与 Phaser 运行时资源 URL 是否一致。
发布到 HTTPS 静态托管
静态 Phaser 游戏通常不需要自建 Node.js 游戏服务器。生产构建后的 HTML、JavaScript、CSS、图片、音频和 JSON 可以由静态托管平台提供,游戏逻辑仍在玩家浏览器中执行。
这里选择 Cloudflare Pages 的 Direct Upload 模式,使用其官方 Wrangler CLI 上传已构建的 dist。操作前准备 Cloudflare 账号和能够访问网络的终端。
首次发布依次执行:
npx wrangler login
npx wrangler pages project create
npx wrangler pages deploy dist --branch=main第一条命令通过浏览器完成账号授权;第二条创建 Pages 项目,并在交互提示中填写项目名称及生产分支 main;第三条将 dist 发布到所选项目的生产分支。若项目实际生产分支不是 main,必须把命令中的分支名替换为真实值。
预期结果:部署成功后,终端会显示本次部署地址,Pages 项目也会提供 HTTPS 访问域名,例如 https://<PROJECT_NAME>.pages.dev/。这里的 <PROJECT_NAME> 是占位符,实际名称和部署地址以平台返回值为准,不应将示例域名原样用于测试。
在浏览器中打开生产域名,检查地址使用 https://,页面没有证书错误,游戏画布和首屏菜单能够显示。发布时上传的是 dist 内部的站点内容,不能使站点根地址错误地指向 /dist/index.html。

如果以后需要由 Git 提交自动触发生产部署,可以改用 Pages 的 Git 集成模式;但 Direct Upload 项目不能直接切换为 Git 集成项目,应在选择初始部署方式时确认团队需求。
验证线上资源和控制台
生产部署完成后,不要只看画面是否出现。游戏首屏可能只加载少量资源,背景音乐、后续关卡 JSON 或死亡动画可能直到对应操作发生时才请求,因此需要主动触发完整资源加载。
以桌面 Chrome 为例,按 F12 打开开发者工具,进入 Network 面板,勾选 Disable cache,并启用 Preserve log 保留页面跳转前后的请求。保持工具打开后刷新生产页面。
按以下顺序检查:
- 在
Doc和JS过滤器中确认入口 HTML 与主要 JavaScript 文件成功返回,页面没有运行时模块加载错误。 - 在
Img过滤器中检查背景、角色、按钮和图集文件。正常加载通常应返回 HTTP 200,文件大小不能异常地为零。 - 在
Media中检查音频请求,必要时清除过滤条件查看全部请求。确认浏览器获取到了正确的音频文件。 - 在
Fetch/XHR中检查关卡配置 JSON;点击响应内容,确认返回的是预期 JSON,而不是托管平台的 HTML 错误页面。 - 切换到
Console,检查是否出现资源加载失败、未捕获异常、跨域拒绝或混合内容错误。
对于关卡 JSON,除了状态码,还应确认 Content-Type 与响应内容合理,例如 JSON 文件返回 application/json,且响应体能够解析。某些静态托管回退配置可能对不存在的资源返回 HTTP 200 和 index.html,仅依赖状态码会漏掉这种错误。
建议为每种关键资源至少抽查一个真实文件,并记录请求路径、状态码、响应内容和加载结果。资源命名以项目实际文件为准,不要求一定使用 player.png 或 level-1.json。
音频还需要额外验证。现代浏览器通常限制未经用户交互的有声自动播放。可以在第一次点击“开始游戏”后触发背景音乐,再检查能否正常播放、静音和恢复。首屏没有自动发声不一定是部署失败。
回归完整游戏流程
资源请求全部成功,不代表游戏状态管理没有问题。应从生产域名而不是本地开发服务器执行回归,并同时覆盖桌面键盘与移动端触控。
下面是一组最小上线验收用例。测试数据以游戏实际规则为准,例如生命值、分数和死亡复活位置,应与当前项目配置一致。
| 测试场景 | 操作 | 通过标准 |
|---|---|---|
| 首次进入 | 无缓存状态下打开 HTTPS 地址 | 资源加载完成,首屏菜单可操作,没有阻断运行的错误 |
| 开始游戏 | 点击开始,连续移动并跳跃 | 进入正式关卡,角色输入、摄像机及碰撞正常 |
| 暂停与恢复 | 运行中暂停,再点击继续 | 暂停期间玩法逻辑冻结,菜单仍可交互,恢复后不重复注册事件 |
| 死亡处理 | 主动触发致命碰撞或使生命归零 | 进入预期死亡状态;按游戏规则重开或从检查点复活,不重复扣血或执行多次重启 |
| 通关结算 | 到达终点并触发胜利条件 | 只结算一次,最终分数正确,结算按钮可用 |
| 再次进入 | 刷新页面并重新开始游戏 | 进度按存档规则恢复,或正确初始化新游戏,未出现旧资源引用 |
对暂停状态,可先让敌人开始巡逻,点击暂停后观察其位置及计时器是否停止;恢复后确认运动继续,而不是出现两倍速度或两套重复计时逻辑。
对死亡和结算,重点检查一次性状态锁。若角色持续接触危险区域,死亡逻辑不应在连续物理帧中多次触发;若角色停留在终点区域,也不应重复加分、重复弹窗或多次切换场景。
移动端至少使用一台实际手机验证横竖屏切换、触控按钮命中、页面滚动冲突、音频解锁和后台切换恢复。桌面 DevTools 的设备模拟可以辅助发现布局问题,但不能完全替代真实手机浏览器。
排除上线后常见故障
当本地正常而生产异常时,优先排查资源路径、实际响应和浏览器安全策略,再修改 Phaser 场景逻辑。以下情况可以直接定位到具体检查点。
| 故障现象 | 定位与修复 |
|---|---|
| 页面空白,脚本返回 404 | 检查 dist/index.html 引用路径、托管根目录与 Vite base;重新构建并发布完整产物 |
| 图片正常,后续关卡加载失败 | 在 Network 中检查 JSON URL、大小写与响应体;将关卡文件放到实际会被发布的位置 |
| JSON 状态码为 200 但解析失败 | 确认响应是否实际为 HTML 回退页面,修正错误路径或托管回退规则 |
| 首次进入没有音乐 | 检查是否被浏览器自动播放策略阻止,并在明确的点击或触摸操作后请求播放 |
| 部署更新后仍显示旧内容 | 检查缓存、Service Worker 与实际部署版本,执行禁用缓存的硬刷新,并清理错误的旧缓存策略 |
| HTTPS 页面中的部分资源失败 | 检查是否仍引用 http:// 资源,避免混合内容,并优先使用同源 HTTPS 静态资源 |
其中路径大小写尤其容易遗漏:本地开发环境如果使用大小写不敏感的文件系统,Player.png 与 player.png 可能看似等价,但在大小写敏感的部署环境中会成为不同路径。上线前应统一资源文件名与代码引用。
每次修复后都应重新执行生产构建、部署和受影响用例,同时至少复查一次开始、暂停、死亡及结算主链路。最后保存通过验收的部署地址、代码版本、测试设备和结果记录;若新版本出现阻断故障,应使用托管平台的历史部署能力恢复已验证的版本,再定位问题。只有生产 HTTPS 地址上的资源与交互都通过检查,才能将本次版本标记为可上线。