游戏引擎 / 系统课时

用 Vite 生成生产环境资源

用 Vite 生成生产环境资源

本课把 Phaser 4 项目从开发状态变成可部署的静态文件:执行 Vite 生产构建,检查子路径部署对脚本与图片地址的影响,再用预览服务器验收 dist。完成后应能识别并修复上线常见的空白画布与资源 404。

学习目标

  • 运行生产构建,并识别 dist 中需要部署的文件。
  • 正确设置 Vite 的 base,让 Phaser 动态加载的资源使用相同前缀。
  • 用预览与浏览器开发者工具验证构建产物。

确认部署路径与构建配置

先在项目根目录确认存在 package.json、index.html,并已安装依赖。package.json 的 scripts 应包含 build 对应 vite build、preview 对应 vite preview;若缺失,只补这两项,不要覆盖其他脚本。

假设最终地址为 https://example.com/game/,就必须把 base 设置成 /game/。根域名直接访问的站点使用默认的 /。下面是只有基础选项时可用的完整 vite.config.js;若项目已经有插件、别名或其他配置,仅向原配置对象添加 base。

js
import { defineConfig } from 'vite';

export default defineConfig({
  // 与正式部署的 URL 前缀保持一致,保留尾部斜杠
  base: '/game/',
});

该设置会让 Vite 在构建时修正入口 HTML、JS 导入的资源和 CSS 中受管理的资源地址;但不能指望它自动改写 Phaser 加载器中的任意字符串路径。改完配置后必须重新构建才会生效。

生成并检查 dist

在包含 package.json 的目录执行构建,再检查入口文件是否生成。这里假定项目已定义上述 build 脚本,且使用 Vite 默认输出目录 dist。

bash
npm run build
node -e "const fs = require('node:fs'); console.log(fs.existsSync('dist/index.html') ? 'dist/index.html OK' : 'dist/index.html MISSING')"

预期结果(省略版本、体积与耗时不固定的 Vite 构建日志):

text
dist/index.html OK

还要打开 dist/index.html,确认入口脚本引用指向 /game/assets/ 下的打包文件;dist/assets/ 中通常能找到带哈希后缀的 JS 文件,具体名字由构建决定。放在 public/ 下的图片和音频会原样复制到 dist/ 对应位置,不自动添加文件名哈希。

修正 Phaser 资源请求

例如资源原本位于 public/assets/hero.png,构建后将位于 dist/assets/hero.png。部署到 /game/ 后,浏览器应请求 /game/assets/hero.png,而非 /assets/hero.png。Vite 不会替 Phaser 自动修正 this.load.image() 里的根路径字符串。

Vite 构建文件与 Phaser 运行时资源 URL 的映射关系

片段示例:以下方法放在已有的 Phaser.Scene 子类中,要求上述图片实际存在,并且该场景没有额外设置互相冲突的加载路径。

js
preload() {
  // public 下的文件需由运行时显式附加 base 前缀
  this.load.setBaseURL(import.meta.env.BASE_URL);
  this.load.image('hero', 'assets/hero.png');
}

重新构建后,请在浏览器 Network 面板确认 hero.png 请求地址为 /game/assets/hero.png,返回 200。setBaseURL() 会影响之后加入加载队列的相对路径;若原代码已对单个资源使用完整 /game/... URL,就不要再重复拼接前缀。对于放在 src/ 中并由 JS 静态导入的资源,优先让 Vite 接管 URL 生成。

预览产物并排除上线故障

构建成功后运行本地预览。--strictPort 保证 4173 被占用时直接报错,避免误测其他端口;该命令会持续运行,检查结束按 Ctrl+C 停止。

bash
npm run preview -- --host 127.0.0.1 --port 4173 --strictPort

预期访问地址(端口已由命令固定):

text
http://127.0.0.1:4173/game/

在该地址打开游戏,按 F12 进入开发者工具的 Network 面板,勾选 Disable cache 后刷新。先确认 HTML、JS、图片、音频请求没有 404,再检查 Console 是否出现脚本加载或 Phaser 资源解码错误;最后实际测试开始游戏、场景切换、拾取与重新加载页面。

现象 优先检查及修复
/assets/hero.png 返回 404 Phaser 使用了站点根路径;按 BASE_URL 补上 /game/
/game/game/assets/hero.png 返回 404 setBaseURL() 与资源 URL 重复添加前缀;只保留一处
JS 请求返回 HTML 或 MIME 类型报错 静态服务器的 /game/ 映射错误;应把 dist 的内容部署到该 URL 前缀下

预览通过后,交付的是 dist 内的构建产物,不是 src 和开发服务器。vite preview 只用于本地验收;正式上线仍需由静态托管服务按相同的 /game/ 路径提供文件,并在上线地址复测资源请求。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Vite 生成生产环境资源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通