第一次装 EVA 的人最容易卡在npm install跑完的那一刻。依赖是装上了node_modules里躺着一长串eva/eva.js、eva/plugin-renderer、eva/plugin-renderer-img把项目仓库 README 里的示例代码粘进编辑器满屏红色波浪线好不容易不报错了npm run dev打开浏览器页面干干净净——一片白。这跟你的 Node 版本没关系跟网络也没关系根源在于 EVA 这个开源项目的组织方式不走一个包解决所有事的路子引擎内核、渲染器、各类组件全是独立发布的包核心包只提供最基础的容器和调度能力你不主动装渲染器它连一块画布都不会创建。这篇安装与使用指南就把 EVA 从零到跑通、再到能拿去做东西的完整链路拆一遍包怎么挑、怎么装、装完之后代码怎么组织、跑起来之后哪几个位置最容易出问题、出问题怎么定位。适合两类人看——一类是刚接触这套框架、想快速验证它能不能扛住自己需求的前端另一类是用过别的 2D 图形库想知道 EVA 这套 ECS 的路子到底有什么不一样的人。下面所有命令和配置都在实际项目里跑过遇到不确定的地方我会明确标出来你按自己装的版本再核对一次。1. EVA 的运行模型决定了它不能一把梭装完1.1 ECS 架构在你敲第一条安装命令时就暴露了EVA 的骨架是 ECS也就是 Entity-Component-System。这三个词听起来学术落到代码里其实很朴素实体是一个空壳节点组件是挂在节点上的数据块系统是遍历所有节点、按组件数据干活的执行者。打个比方实体是舞台上的演员本人一个空的人形组件是给他贴的标签——会走路穿着红衣服有碰撞体积系统则是导演每帧扫一遍全场看到带会走路标签的演员就让他往前挪两步。这套模型最大的好处是解耦你新增一种能力不用去改演员类、也不用改导演类只要写一个新组件加一个新系统注册进去就生效。代价就是能力全在包里。EVA 把渲染图片这件事做成了一个包把渲染文本做成了另一个包把响应触摸又做成了第三个包。内核里根本不存在Image这种东西你不装对应包内核压根不认识它。所以你在别处养成的习惯——npm i xxx一把梭然后import xxx from xxx开始写——在 EVA 这儿会直接翻车。你得先想清楚这个项目要显示什么、要不要交互、要不要动画然后再去挑包。这个顺序反了后面就是无穷无尽的undefined is not a constructor。1.2 Game、GameObject、Component 三层关系先捋清楚装包之前这三个对象的职责必须先在心里摆正否则装完也用不明白。Game是整个应用的根容器一个页面通常只有一个。它负责持有系统列表、驱动主循环、管理场景Scene。你可以把它理解成引擎实例 画布持有者。构造它的时候要把系统数组传进去这一步就决定了你这个应用具备哪些能力。GameObject是场景里的节点可以有父子层级自带一个内置的Transform组件负责位置、尺寸、缩放、旋转、锚点、透明度、可见性这些基础属性。构造函数第二个参数就是给Transform传初值的地方。Component挂在GameObject上是一个纯数据加少量方法的对象。比如Img组件只存一个资源名Text组件只存文案和样式真正的绘制动作由对应的System在主循环里完成。理解了这层你就明白为什么装包这件事在 EVA 里格外重要装的是 System用的是 Component。少了 SystemComponent 就是一个没人理的数据块挂上去也不会有任何画面。1.3 拆包的代价与收益得提前认拆包这件事是有代价的安装步骤变多版本要自己对文档得跳着看。但它换来的东西也很实在。第一是体积可控。做一个只显示几张图的小活动页你就不用把骨骼动画、遮罩、图形绘制这些全打进产物里。第二是渲染器可替换——同一套业务代码底层可以跑 Canvas 也可以跑 WebGL切换只改一个枚举值。第三是包与包之间边界清晰出问题的时候能快速定位到是哪一层没装对。我的建议是第一次上手先按最小组合装跑通了再逐个加包。一上来把十几个包全装上出了问题你根本不知道该从哪儿查。最小组合只有四个内核、渲染器基础、图片渲染、事件。这四个能撑起一个点一下换张图的完整 Demo足够你判断这套框架合不合手。2. 环境与脚手架Node 版本、包管理器、构建工具的三次取舍2.1 Node 版本不用追新但要避开两个区间EVA 的包在发布时做了 CommonJS 和 ESM 双份产物对 Node 的要求本身不苛刻我实测 Node 16 到 20 都能正常构建运行。真正容易出问题的是两头的极端版本太老的14 及以下在解析exports字段时可能拿不到正确入口太新的偶发情况和某些构建工具的依赖树打架。判断标准很朴素你的构建工具能跑EVA 就能跑。所以先确定构建工具再倒推 Node 版本比反过来靠谱。团队协作的话在项目根目录放一个.nvmrc把版本钉住省得每个人环境不一样导致我这儿好的啊。# .nvmrc 202.2 npm、yarn、pnpm 在 EVA 项目上的实际差异三个包管理器我都试过结论是都能用但 pnpm 需要额外配置。npm 和 yarn 装完直接跑因为 EVA 的包之间是常规的扁平依赖没有复杂的 peer 关系。pnpm 的严格 node_modules 结构会把你没有显式声明的依赖藏起来而 EVA 某些插件包在内部引用了兄弟包这时候就会报找不到模块。真要用 pnpm在.npmrc里加一行# .npmrc shamefully-hoisttrue这行的意思是把依赖提升到顶层牺牲一点隔离性换兼容性。对 EVA 这种插件化拆包的库我觉得这笔交易划算。包管理器开箱可用需要注意npm是装包慢一些锁文件体积大yarn是建议用 classic 版本berry 的 PnP 模式会出问题pnpm需配置必须开shamefully-hoist否则插件包互相引用会失败提示如果你在团队里推 pnpm最好把.npmrc一起提交别指望每个人自己记得改。2.3 Vite 还是 Webpack从资源路径这个点倒推这两个构建工具都能配 EVA但体验差别集中在静态资源处理上。EVA 的资源系统接受的是一个 URL 字符串比如{ image: { type: png, url: ./assets/bg.png } }。注意这个字符串是运行时才被 fetch 的构建工具不会去分析它、不会帮你加 hash、不会帮你搬到dist目录。这是所有人第一次打包上线时踩的头号坑本地 dev 好好的build之后图片全 404。Vite 下最省事的解法是把资源丢进public目录然后写绝对路径/assets/bg.png。public里的东西会原样复制到产物根目录路径不变最稳。缺点是失去了 hash 缓存控制。想要 hash 就用new URL语法让 Vite 在构建期解析const bgUrl new URL(./assets/bg.png, import.meta.url).href; resource.addResource([ { name: bg, type: RESOURCE_TYPE.IMAGE, src: { image: { type: png, url: bgUrl } }, preload: true, }, ]);Webpack 5 下对应的写法是new URL(./assets/bg.png, import.meta.url)行为一致。我个人的取舍是活动页、投放页这种改一次发一次的用public直出简单不出错需要长期迭代、在意缓存命中的项目用new URL走 hash。别在一个项目里混着用维护起来会疯。2.4 一份能直接抄的项目骨架目录结构我固定用这一套跑过好几个项目都没出问题eva-demo/ ├─ public/ │ └─ assets/ # 不需要 hash 的图片音效 ├─ src/ │ ├─ assets/ # 走构建的图片 │ ├─ game/ │ │ ├─ index.js # Game 实例创建与系统注册 │ │ ├─ resources.js # 资源清单集中管理 │ │ └─ scenes/ # 各场景的构建函数 │ └─ main.js ├─ index.html ├─ vite.config.js └─ package.jsonresources.js单独抽出来的原因是EVA 的资源注册是全局的散落在各个场景文件里排查这个图到底有没有加载会非常痛苦。集中一处出了问题一眼能扫完。vite.config.js里我只加两行关键配置import { defineConfig } from vite; export default defineConfig({ server: { host: true, port: 5173, }, build: { assetsInlineLimit: 0, }, });assetsInlineLimit: 0是为了防止小图被转成 base64。EVA 的资源加载器对 base64 的data:协议支持取决于具体版本我遇到过小图被内联后加载失败的情况直接关掉这个优化最省心。3. 依赖安装核心包、渲染器、组件包的依赖关系图3.1 三层结构装之前先分层EVA 的包可以分成三层理解这个分层比记住具体包名重要得多。第一层是内核eva/eva.js。它提供Game、GameObject、resource、Transform、RESOURCE_TYPE这些基础设施。这一层必装没有替代品。第二层是渲染器基础eva/plugin-renderer。它提供RendererSystem负责创建画布、驱动渲染循环。注意它本身不渲染任何具体内容只是把渲染管线搭起来。这一层也是必装的装完不加任何渲染组件页面依然是一片空白但至少不会报错。第三层是各类组件包eva/plugin-renderer-img、eva/plugin-renderer-text、eva/plugin-renderer-sprite……每个包提供一对 System 和 Component。这一层按需装。层与层之间的依赖是单向的第三层依赖第二层第二层依赖第一层。所以你装错了顺序不会出问题但漏装某一层会出问题。最常见的错误是只装了eva/plugin-renderer-img忘了装eva/plugin-renderer结果RendererSystem是undefined。3.2 一份按场景划分的安装清单我把常用的包按使用场景整理成表你对着自己项目勾一下就行包名提供的能力什么情况下必装eva/eva.jsGame、GameObject、resource、Transform永远eva/plugin-rendererRendererSystem、RENDER_TYPE永远eva/plugin-renderer-img单张图片渲染 Img显示静态图eva/plugin-renderer-sprite序列帧图集动画 Sprite帧动画eva/plugin-renderer-text文本渲染 Text有任何文字eva/plugin-renderer-event事件响应 Event需要点击/滑动eva/plugin-renderer-graphics基础图形绘制 Graphics要画矩形、圆、线eva/plugin-renderer-nine-patch九宫格拉伸 NinePatch弹窗底板、按钮底eva/plugin-renderer-mask遮罩 Mask圆形头像、进度条eva/plugin-transition补间动画 Transition要做缓动效果eva/plugin-renderer-spine骨骼动画有骨骼资源eva/plugin-stats帧率面板调试阶段强烈建议最小可运行组合的命令长这样npm i eva/eva.js eva/plugin-renderer eva/plugin-renderer-img eva/plugin-renderer-event3.3 版本对齐这件事别偷懒EVA 的各个包是独立发版的主包和插件包并不总是同一个版本号。这是拆包架构的必然结果也是新手最容易懵的地方。装完之后第一件事跑一下这条命令看一眼实际的依赖树npm ls --depth1 | grep eva输出里如果出现了多个不同版本的eva/eva.js比如 1.x 和一个 0.x 同时存在那基本可以确定后面要出玄学问题——两个版本的GameObject类不是同一个类instanceof判断会失效组件挂载会静默失败。处理办法是把所有eva/*包在package.json里写成同一个小版本区间比如全部用^1.0.0然后删掉node_modules和锁文件重装。这一招看着粗暴但胜过花两小时查一个本可以避免的 bug。注意不要在一个项目里同时依赖某个eva/*包的多个大版本除非你非常确定自己在做什么。跨大版本的对象互相传递是最难排查的一类问题。3.4 装完报错的三种典型形态第一种Cannot find module eva/xxx。八成是包名拼错或者漏装。EVA 的包名都在eva/作用域下部分包有plugin-renderer-前缀部分没有比如plugin-transition、plugin-stats抄包名的时候留心。第二种RendererSystem is not a constructor。这说明eva/plugin-renderer没装或者装了但导出名不对。检查一下 import 语句RENDER_TYPE也是从这个包导出的。第三种编译期报 ESM/CJS 互操作错误提示require() of ES Module。这通常发生在用 Node 直接跑某些配置脚本时。解决方向是确认你的构建工具版本足够新或者把相关配置改成.mjs后缀。4. 跑通第一个场景Canvas 挂载与资源预加载4.1 RendererSystem 的参数逐个掰开渲染器是整条链路的起点它的参数决定了后面所有坐标和清晰度的基准。我在项目里一般这么写import { Game, GameObject, resource, RESOURCE_TYPE } from eva/eva.js; import { RendererSystem, RENDER_TYPE } from eva/plugin-renderer; const canvas document.getElementById(game-canvas); const dpr Math.min(window.devicePixelRatio || 1, 2); const game new Game({ systems: [ new RendererSystem({ canvas, width: 750, height: 1334, resolution: dpr, renderType: RENDER_TYPE.CANVAS, transparent: false, }), ], autoStart: true, frameRate: 60, });width和height是逻辑尺寸也就是你写业务代码时用的坐标系。移动端项目惯例是 750 宽跟设计稿对齐换算时省心。resolution是像素比它会把真实画布放大到width * resolution然后整体缩回去这样在高分屏上文字和边缘不会糊。我一般把 dpr 卡在 2 以内3 倍屏上收益很小但显存和填充率压力不小。renderType选 Canvas 还是 WebGL判断标准很简单图少、没有大面积频繁重绘、不需要复杂混合模式选 Canvas启动快、兼容好、调试直观图多、有大量半透明叠加、要做滤镜效果选 WebGL。这个值后期想换改一行就行业务代码不用动。transparent: true会让画布背景透明适合把游戏嵌在已有页面里。设成 true 之后记得给父容器一个背景色否则你会看到白屏——其实是透明的底下什么都没有。autoStart: true表示构造函数返回后立刻开始主循环。调试阶段我建议先设成 false手动调game.start()这样你能在循环跑起来之前把场景全部构建好避免出现第一帧只渲染了一半元素的闪烁。4.2 资源注册的字段结构这是 EVA 里最容易写错的一段配置格式记牢resource.addResource([ { name: bg, type: RESOURCE_TYPE.IMAGE, src: { image: { type: png, url: /assets/bg.png, }, }, preload: true, }, ]);name是你后面在组件里引用的唯一标识全局唯一重名会导致后注册的覆盖先注册的。type是资源类型枚举图片用RESOURCE_TYPE.IMAGE图集动画用RESOURCE_TYPE.SPRITE。src是一个对象键名跟类型相关——图片类资源统一放在image键下面图集资源需要同时提供image和json两个键。preload: true表示注册后立刻进入加载队列。图集资源的写法{ name: hero, type: RESOURCE_TYPE.SPRITE, src: { image: { type: png, url: /assets/hero.png }, json: { type: json, url: /assets/hero.json }, }, preload: true, }hero.json描述每一帧在图集里的位置和尺寸这个格式有既定规范一般由纹理打包工具导出不用手写。4.3 加载时序先 add 后 new 才会白屏addResource是同步的注册但加载是异步的。你在preload: true之后紧接着创建Img组件那一刻图片很可能还没下载完组件渲染时拿不到贴图画面上就是空的。等加载完了如果没有任何机制触发重绘这个空状态会一直挂着。正确做法是等加载完成再构建场景async function bootstrap() { resource.addResource([/* ... */]); await resource.load(); buildScene(); game.start(); }resource.load()返回 Promise全部资源就绪后 resolve。如果只想等某几个资源可以传名称数组。EVA 的资源系统也提供loaded事件两种方式挑一种别混用。还有一种隐性白屏组件挂上了、资源也加载了但GameObject的size是 0。Transform的尺寸默认不是从贴图自动推导的你得显式给size否则就是一个 0×0 的节点画了等于没画。这个坑我踩过查了半小时以为是资源路径问题。5. 把静态画面变成能交互的东西精灵、文本与事件5.1 图片和帧动画是两套资源两套组件单图用Img动作用Sprite两者不通用。这是新手常混的地方。import { ImgSystem, Img } from eva/plugin-renderer-img; const bg new GameObject(bg, { size: { width: 750, height: 1334 }, position: { x: 0, y: 0 }, origin: { x: 0, y: 0 }, anchor: { x: 0, y: 0 }, }); bg.addComponent(new Img({ resource: bg })); game.scene.addChild(bg);origin和anchor两个参数建议一开始就搞懂。origin定义的是自身坐标系原点在节点内的相对位置anchor定义的是这个节点在父节点坐标系中的定位基准点。两个都设成{x: 0.5, y: 0.5}节点就会以自己中心对齐到position指定的位置做居中布局最省事。都设成{x: 0, y: 0}则是左上角对齐做铺满全屏的背景图用这个。混着用会出现位置算得对但画面偏了的现象。帧动画import { SpriteSystem, Sprite } from eva/plugin-renderer-sprite; const hero new GameObject(hero, { size: { width: 200, height: 200 }, position: { x: 375, y: 800 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); const sprite hero.addComponent(new Sprite({ resource: hero, animationName: idle, })); sprite.play(idle);animationName对应图集 JSON 里定义的动画名拼错不会报错只是不播。所以图集动画不动的时候先打印一下资源加载后的动画名列表核对。5.2 文本渲染字体和清晰度是两个独立问题import { TextSystem, Text } from eva/plugin-renderer-text; const label new GameObject(label, { size: { width: 400, height: 80 }, position: { x: 375, y: 400 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); label.addComponent(new Text({ text: 开始游戏, style: { fontSize: 36, fontFamily: Arial, sans-serif, fill: 0xffffff, fontWeight: bold, }, }));fill用的是数字形式的颜色值不是 CSS 字符串写成#ffffff不生效。这一点跟 Canvas 原生 API 的习惯不一样容易忘。字体加载是另一回事。fontFamily里写的字体如果没在页面里加载好渲染时用的就是系统兜底字体字形和设计稿对不上。自定义字体要么在 HTML 里放font-face并预加载要么用document.fonts.load()等待字体就绪再构建场景。我一般把字体加载和资源加载放在同一个Promise.all里两边都完成再game.start()。清晰度问题单独说文字发虚通常是resolution没设或者被设成了 1。渲染器按逻辑尺寸建画布没有像素比放大在高分屏上就是一个逻辑像素铺到三个物理像素上糊是必然的。把resolution按 dpr 设上去同时确认对应TextSystem已经注册在系统列表里。5.3 事件系统的坐标系换算import { EventSystem, Event } from eva/plugin-renderer-event; const btn new GameObject(btn, { size: { width: 300, height: 120 }, position: { x: 375, y: 900 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); const evt btn.addComponent(new Event()); evt.on(tap, () { console.log(点击生效); });不传area时组件默认用节点的size作为命中区域这是最常用的方式。要做异形热区传area指定矩形范围。坐标系这块有个必踩的坑渲染器做了分辨率放大之后触摸坐标和逻辑坐标不是同一个尺度。EVA 的事件系统在内部处理了这个换算但前提是你的RendererSystem参数配置正确。如果你自己在外面又套了一层 CSS 缩放比如给 canvas 设了width: 100%换算就会错位表现为点左边触发了右边。正确做法是让 canvas 的 CSS 尺寸和逻辑尺寸保持一致的比例关系缩放由渲染器统一处理不要让 CSS 和渲染器各管一套。移动端适配我一般按屏幕宽度算出缩放比然后对 canvas 元素做transform: scale()父容器再居中这样事件换算链路是干净的。6. 上线前的自查白屏、404、掉帧三类问题的排查链路6.1 白屏按四层往下剥白屏是最常见的求助我给一套固定的排查顺序从下往上剥基本十分钟内能定位。第一层看控制台有没有报错。有明确报错就先解决报错别往下走。xxx is not a constructor基本就是漏装包。第二层看 canvas 元素在不在 DOM 里。打开元素检查器找canvas。找不到说明RendererSystem根本没成功初始化回头检查参数里的canvas是不是拿到了一个null——最常见的原因是脚本在 DOM 就绪之前执行了。第三层看 canvas 的尺寸。找到元素了看它的width和height属性。如果是 0说明参数没传对。如果是750×1334这种正常值但画面还是空的往下走。第四层看场景里有没有子节点。在控制台里打印game.scene.children.length。是 0说明构建场景的代码压根没执行——大概率是上面await的地方挂了或者 Promise 没等到。不是 0说明节点在但没画出来回去查size、visible、alpha、资源的name这几项。这四层走完还白屏的话把renderType临时切成 Canvas很多时候 WebGL 上下文创建失败比如在虚拟机的无头环境里会静默黑屏切换一下立刻就能确认。6.2 打包后资源 404三种成因对应三种解法本地好、线上挂八成是资源路径。分清是哪种现象成因解法请求路径里没有 hash指向了不存在的旧文件public目录里的文件名手写错了或者部署时没同步核对public与代码里的路径是否字面一致请求路径带了错误的域名或前缀用了绝对路径/assets/x.png但应用部署在子路径下改用相对于base的路径或把base配到构建配置里请求路径是[object Object]之类url字段传的不是字符串多半是new URL()忘了取.href检查url变量类型第二种在部署到子目录时特别高发。public资源的路径要跟着构建配置的base走base改了路径前缀就得跟着改最稳的做法是用环境变量拼前缀不写死在代码里。还有一种隐蔽的图片确实 200 了但画面上没有。这时候去看响应头里的Content-Type。某些静态服务器对不认识的扩展名会返回application/octet-stream图片解析器接不住静默失败。这种情况改服务器配置或者换个文件名后缀就能验证。6.3 帧率和渲染模式别急着上 WebGL很多人默认觉得 WebGL 一定比 Canvas 快实际项目里不一定。EVA 的 Canvas 渲染器在元素数量少几十个以内、绘制区域小的情况下表现相当好启动还快。真正需要 WebGL 的是这几种场景同屏上百个半透明元素叠加、需要做滤镜和混合模式、需要高频重绘大面积区域。判断方法别靠猜装eva/plugin-stats把帧率面板挂上去看。import { StatsSystem } from eva/plugin-stats; game new Game({ systems: [ new RendererSystem({ /* ... */ }), new StatsSystem(), ], });面板上如果帧率稳定在 60别动。如果掉到 40 以下先做这三件事再考虑换渲染模式把不可见的节点visible设成 false 而不是留在场景里把长时间不变的静态内容合并到一张图上把每帧都在改的属性位置、缩放和不变的属性分开避免同一节点上挂太多组件。还有一个小技巧frameRate从 60 降到 30肉眼对静态为主的界面几乎无感但 CPU 占用能直接砍半。展示型页面我经常这么干尤其是嵌在长页面里的那种。我个人在几个项目里用下来EVA 这套东西最大的门槛不在 API而在装和配这两步——把包按层装对、把资源路径在构建工具里理顺后面写业务代码其实相当顺组件化的思路一旦建立起来加东西就是拼积木。反过来如果这两步糊弄过去了后面每加一个功能都会撞一次同样的墙。所以第一次上手别急着写功能先花二十分钟把最小组合跑通、把目录结构定下来这笔时间花得值。
第一次装 EVA 的人最容易卡在npm install跑完的那一刻。依赖是装上了node_modules里躺着一长串eva/eva.js、eva/plugin-renderer、eva/plugin-renderer-img把项目仓库 README 里的示例代码粘进编辑器满屏红色波浪线好不容易不报错了npm run dev打开浏览器页面干干净净——一片白。这跟你的 Node 版本没关系跟网络也没关系根源在于 EVA 这个开源项目的组织方式不走一个包解决所有事的路子引擎内核、渲染器、各类组件全是独立发布的包核心包只提供最基础的容器和调度能力你不主动装渲染器它连一块画布都不会创建。这篇安装与使用指南就把 EVA 从零到跑通、再到能拿去做东西的完整链路拆一遍包怎么挑、怎么装、装完之后代码怎么组织、跑起来之后哪几个位置最容易出问题、出问题怎么定位。适合两类人看——一类是刚接触这套框架、想快速验证它能不能扛住自己需求的前端另一类是用过别的 2D 图形库想知道 EVA 这套 ECS 的路子到底有什么不一样的人。下面所有命令和配置都在实际项目里跑过遇到不确定的地方我会明确标出来你按自己装的版本再核对一次。1. EVA 的运行模型决定了它不能一把梭装完1.1 ECS 架构在你敲第一条安装命令时就暴露了EVA 的骨架是 ECS也就是 Entity-Component-System。这三个词听起来学术落到代码里其实很朴素实体是一个空壳节点组件是挂在节点上的数据块系统是遍历所有节点、按组件数据干活的执行者。打个比方实体是舞台上的演员本人一个空的人形组件是给他贴的标签——会走路穿着红衣服有碰撞体积系统则是导演每帧扫一遍全场看到带会走路标签的演员就让他往前挪两步。这套模型最大的好处是解耦你新增一种能力不用去改演员类、也不用改导演类只要写一个新组件加一个新系统注册进去就生效。代价就是能力全在包里。EVA 把渲染图片这件事做成了一个包把渲染文本做成了另一个包把响应触摸又做成了第三个包。内核里根本不存在Image这种东西你不装对应包内核压根不认识它。所以你在别处养成的习惯——npm i xxx一把梭然后import xxx from xxx开始写——在 EVA 这儿会直接翻车。你得先想清楚这个项目要显示什么、要不要交互、要不要动画然后再去挑包。这个顺序反了后面就是无穷无尽的undefined is not a constructor。1.2 Game、GameObject、Component 三层关系先捋清楚装包之前这三个对象的职责必须先在心里摆正否则装完也用不明白。Game是整个应用的根容器一个页面通常只有一个。它负责持有系统列表、驱动主循环、管理场景Scene。你可以把它理解成引擎实例 画布持有者。构造它的时候要把系统数组传进去这一步就决定了你这个应用具备哪些能力。GameObject是场景里的节点可以有父子层级自带一个内置的Transform组件负责位置、尺寸、缩放、旋转、锚点、透明度、可见性这些基础属性。构造函数第二个参数就是给Transform传初值的地方。Component挂在GameObject上是一个纯数据加少量方法的对象。比如Img组件只存一个资源名Text组件只存文案和样式真正的绘制动作由对应的System在主循环里完成。理解了这层你就明白为什么装包这件事在 EVA 里格外重要装的是 System用的是 Component。少了 SystemComponent 就是一个没人理的数据块挂上去也不会有任何画面。1.3 拆包的代价与收益得提前认拆包这件事是有代价的安装步骤变多版本要自己对文档得跳着看。但它换来的东西也很实在。第一是体积可控。做一个只显示几张图的小活动页你就不用把骨骼动画、遮罩、图形绘制这些全打进产物里。第二是渲染器可替换——同一套业务代码底层可以跑 Canvas 也可以跑 WebGL切换只改一个枚举值。第三是包与包之间边界清晰出问题的时候能快速定位到是哪一层没装对。我的建议是第一次上手先按最小组合装跑通了再逐个加包。一上来把十几个包全装上出了问题你根本不知道该从哪儿查。最小组合只有四个内核、渲染器基础、图片渲染、事件。这四个能撑起一个点一下换张图的完整 Demo足够你判断这套框架合不合手。2. 环境与脚手架Node 版本、包管理器、构建工具的三次取舍2.1 Node 版本不用追新但要避开两个区间EVA 的包在发布时做了 CommonJS 和 ESM 双份产物对 Node 的要求本身不苛刻我实测 Node 16 到 20 都能正常构建运行。真正容易出问题的是两头的极端版本太老的14 及以下在解析exports字段时可能拿不到正确入口太新的偶发情况和某些构建工具的依赖树打架。判断标准很朴素你的构建工具能跑EVA 就能跑。所以先确定构建工具再倒推 Node 版本比反过来靠谱。团队协作的话在项目根目录放一个.nvmrc把版本钉住省得每个人环境不一样导致我这儿好的啊。# .nvmrc 202.2 npm、yarn、pnpm 在 EVA 项目上的实际差异三个包管理器我都试过结论是都能用但 pnpm 需要额外配置。npm 和 yarn 装完直接跑因为 EVA 的包之间是常规的扁平依赖没有复杂的 peer 关系。pnpm 的严格 node_modules 结构会把你没有显式声明的依赖藏起来而 EVA 某些插件包在内部引用了兄弟包这时候就会报找不到模块。真要用 pnpm在.npmrc里加一行# .npmrc shamefully-hoisttrue这行的意思是把依赖提升到顶层牺牲一点隔离性换兼容性。对 EVA 这种插件化拆包的库我觉得这笔交易划算。包管理器开箱可用需要注意npm是装包慢一些锁文件体积大yarn是建议用 classic 版本berry 的 PnP 模式会出问题pnpm需配置必须开shamefully-hoist否则插件包互相引用会失败提示如果你在团队里推 pnpm最好把.npmrc一起提交别指望每个人自己记得改。2.3 Vite 还是 Webpack从资源路径这个点倒推这两个构建工具都能配 EVA但体验差别集中在静态资源处理上。EVA 的资源系统接受的是一个 URL 字符串比如{ image: { type: png, url: ./assets/bg.png } }。注意这个字符串是运行时才被 fetch 的构建工具不会去分析它、不会帮你加 hash、不会帮你搬到dist目录。这是所有人第一次打包上线时踩的头号坑本地 dev 好好的build之后图片全 404。Vite 下最省事的解法是把资源丢进public目录然后写绝对路径/assets/bg.png。public里的东西会原样复制到产物根目录路径不变最稳。缺点是失去了 hash 缓存控制。想要 hash 就用new URL语法让 Vite 在构建期解析const bgUrl new URL(./assets/bg.png, import.meta.url).href; resource.addResource([ { name: bg, type: RESOURCE_TYPE.IMAGE, src: { image: { type: png, url: bgUrl } }, preload: true, }, ]);Webpack 5 下对应的写法是new URL(./assets/bg.png, import.meta.url)行为一致。我个人的取舍是活动页、投放页这种改一次发一次的用public直出简单不出错需要长期迭代、在意缓存命中的项目用new URL走 hash。别在一个项目里混着用维护起来会疯。2.4 一份能直接抄的项目骨架目录结构我固定用这一套跑过好几个项目都没出问题eva-demo/ ├─ public/ │ └─ assets/ # 不需要 hash 的图片音效 ├─ src/ │ ├─ assets/ # 走构建的图片 │ ├─ game/ │ │ ├─ index.js # Game 实例创建与系统注册 │ │ ├─ resources.js # 资源清单集中管理 │ │ └─ scenes/ # 各场景的构建函数 │ └─ main.js ├─ index.html ├─ vite.config.js └─ package.jsonresources.js单独抽出来的原因是EVA 的资源注册是全局的散落在各个场景文件里排查这个图到底有没有加载会非常痛苦。集中一处出了问题一眼能扫完。vite.config.js里我只加两行关键配置import { defineConfig } from vite; export default defineConfig({ server: { host: true, port: 5173, }, build: { assetsInlineLimit: 0, }, });assetsInlineLimit: 0是为了防止小图被转成 base64。EVA 的资源加载器对 base64 的data:协议支持取决于具体版本我遇到过小图被内联后加载失败的情况直接关掉这个优化最省心。3. 依赖安装核心包、渲染器、组件包的依赖关系图3.1 三层结构装之前先分层EVA 的包可以分成三层理解这个分层比记住具体包名重要得多。第一层是内核eva/eva.js。它提供Game、GameObject、resource、Transform、RESOURCE_TYPE这些基础设施。这一层必装没有替代品。第二层是渲染器基础eva/plugin-renderer。它提供RendererSystem负责创建画布、驱动渲染循环。注意它本身不渲染任何具体内容只是把渲染管线搭起来。这一层也是必装的装完不加任何渲染组件页面依然是一片空白但至少不会报错。第三层是各类组件包eva/plugin-renderer-img、eva/plugin-renderer-text、eva/plugin-renderer-sprite……每个包提供一对 System 和 Component。这一层按需装。层与层之间的依赖是单向的第三层依赖第二层第二层依赖第一层。所以你装错了顺序不会出问题但漏装某一层会出问题。最常见的错误是只装了eva/plugin-renderer-img忘了装eva/plugin-renderer结果RendererSystem是undefined。3.2 一份按场景划分的安装清单我把常用的包按使用场景整理成表你对着自己项目勾一下就行包名提供的能力什么情况下必装eva/eva.jsGame、GameObject、resource、Transform永远eva/plugin-rendererRendererSystem、RENDER_TYPE永远eva/plugin-renderer-img单张图片渲染 Img显示静态图eva/plugin-renderer-sprite序列帧图集动画 Sprite帧动画eva/plugin-renderer-text文本渲染 Text有任何文字eva/plugin-renderer-event事件响应 Event需要点击/滑动eva/plugin-renderer-graphics基础图形绘制 Graphics要画矩形、圆、线eva/plugin-renderer-nine-patch九宫格拉伸 NinePatch弹窗底板、按钮底eva/plugin-renderer-mask遮罩 Mask圆形头像、进度条eva/plugin-transition补间动画 Transition要做缓动效果eva/plugin-renderer-spine骨骼动画有骨骼资源eva/plugin-stats帧率面板调试阶段强烈建议最小可运行组合的命令长这样npm i eva/eva.js eva/plugin-renderer eva/plugin-renderer-img eva/plugin-renderer-event3.3 版本对齐这件事别偷懒EVA 的各个包是独立发版的主包和插件包并不总是同一个版本号。这是拆包架构的必然结果也是新手最容易懵的地方。装完之后第一件事跑一下这条命令看一眼实际的依赖树npm ls --depth1 | grep eva输出里如果出现了多个不同版本的eva/eva.js比如 1.x 和一个 0.x 同时存在那基本可以确定后面要出玄学问题——两个版本的GameObject类不是同一个类instanceof判断会失效组件挂载会静默失败。处理办法是把所有eva/*包在package.json里写成同一个小版本区间比如全部用^1.0.0然后删掉node_modules和锁文件重装。这一招看着粗暴但胜过花两小时查一个本可以避免的 bug。注意不要在一个项目里同时依赖某个eva/*包的多个大版本除非你非常确定自己在做什么。跨大版本的对象互相传递是最难排查的一类问题。3.4 装完报错的三种典型形态第一种Cannot find module eva/xxx。八成是包名拼错或者漏装。EVA 的包名都在eva/作用域下部分包有plugin-renderer-前缀部分没有比如plugin-transition、plugin-stats抄包名的时候留心。第二种RendererSystem is not a constructor。这说明eva/plugin-renderer没装或者装了但导出名不对。检查一下 import 语句RENDER_TYPE也是从这个包导出的。第三种编译期报 ESM/CJS 互操作错误提示require() of ES Module。这通常发生在用 Node 直接跑某些配置脚本时。解决方向是确认你的构建工具版本足够新或者把相关配置改成.mjs后缀。4. 跑通第一个场景Canvas 挂载与资源预加载4.1 RendererSystem 的参数逐个掰开渲染器是整条链路的起点它的参数决定了后面所有坐标和清晰度的基准。我在项目里一般这么写import { Game, GameObject, resource, RESOURCE_TYPE } from eva/eva.js; import { RendererSystem, RENDER_TYPE } from eva/plugin-renderer; const canvas document.getElementById(game-canvas); const dpr Math.min(window.devicePixelRatio || 1, 2); const game new Game({ systems: [ new RendererSystem({ canvas, width: 750, height: 1334, resolution: dpr, renderType: RENDER_TYPE.CANVAS, transparent: false, }), ], autoStart: true, frameRate: 60, });width和height是逻辑尺寸也就是你写业务代码时用的坐标系。移动端项目惯例是 750 宽跟设计稿对齐换算时省心。resolution是像素比它会把真实画布放大到width * resolution然后整体缩回去这样在高分屏上文字和边缘不会糊。我一般把 dpr 卡在 2 以内3 倍屏上收益很小但显存和填充率压力不小。renderType选 Canvas 还是 WebGL判断标准很简单图少、没有大面积频繁重绘、不需要复杂混合模式选 Canvas启动快、兼容好、调试直观图多、有大量半透明叠加、要做滤镜效果选 WebGL。这个值后期想换改一行就行业务代码不用动。transparent: true会让画布背景透明适合把游戏嵌在已有页面里。设成 true 之后记得给父容器一个背景色否则你会看到白屏——其实是透明的底下什么都没有。autoStart: true表示构造函数返回后立刻开始主循环。调试阶段我建议先设成 false手动调game.start()这样你能在循环跑起来之前把场景全部构建好避免出现第一帧只渲染了一半元素的闪烁。4.2 资源注册的字段结构这是 EVA 里最容易写错的一段配置格式记牢resource.addResource([ { name: bg, type: RESOURCE_TYPE.IMAGE, src: { image: { type: png, url: /assets/bg.png, }, }, preload: true, }, ]);name是你后面在组件里引用的唯一标识全局唯一重名会导致后注册的覆盖先注册的。type是资源类型枚举图片用RESOURCE_TYPE.IMAGE图集动画用RESOURCE_TYPE.SPRITE。src是一个对象键名跟类型相关——图片类资源统一放在image键下面图集资源需要同时提供image和json两个键。preload: true表示注册后立刻进入加载队列。图集资源的写法{ name: hero, type: RESOURCE_TYPE.SPRITE, src: { image: { type: png, url: /assets/hero.png }, json: { type: json, url: /assets/hero.json }, }, preload: true, }hero.json描述每一帧在图集里的位置和尺寸这个格式有既定规范一般由纹理打包工具导出不用手写。4.3 加载时序先 add 后 new 才会白屏addResource是同步的注册但加载是异步的。你在preload: true之后紧接着创建Img组件那一刻图片很可能还没下载完组件渲染时拿不到贴图画面上就是空的。等加载完了如果没有任何机制触发重绘这个空状态会一直挂着。正确做法是等加载完成再构建场景async function bootstrap() { resource.addResource([/* ... */]); await resource.load(); buildScene(); game.start(); }resource.load()返回 Promise全部资源就绪后 resolve。如果只想等某几个资源可以传名称数组。EVA 的资源系统也提供loaded事件两种方式挑一种别混用。还有一种隐性白屏组件挂上了、资源也加载了但GameObject的size是 0。Transform的尺寸默认不是从贴图自动推导的你得显式给size否则就是一个 0×0 的节点画了等于没画。这个坑我踩过查了半小时以为是资源路径问题。5. 把静态画面变成能交互的东西精灵、文本与事件5.1 图片和帧动画是两套资源两套组件单图用Img动作用Sprite两者不通用。这是新手常混的地方。import { ImgSystem, Img } from eva/plugin-renderer-img; const bg new GameObject(bg, { size: { width: 750, height: 1334 }, position: { x: 0, y: 0 }, origin: { x: 0, y: 0 }, anchor: { x: 0, y: 0 }, }); bg.addComponent(new Img({ resource: bg })); game.scene.addChild(bg);origin和anchor两个参数建议一开始就搞懂。origin定义的是自身坐标系原点在节点内的相对位置anchor定义的是这个节点在父节点坐标系中的定位基准点。两个都设成{x: 0.5, y: 0.5}节点就会以自己中心对齐到position指定的位置做居中布局最省事。都设成{x: 0, y: 0}则是左上角对齐做铺满全屏的背景图用这个。混着用会出现位置算得对但画面偏了的现象。帧动画import { SpriteSystem, Sprite } from eva/plugin-renderer-sprite; const hero new GameObject(hero, { size: { width: 200, height: 200 }, position: { x: 375, y: 800 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); const sprite hero.addComponent(new Sprite({ resource: hero, animationName: idle, })); sprite.play(idle);animationName对应图集 JSON 里定义的动画名拼错不会报错只是不播。所以图集动画不动的时候先打印一下资源加载后的动画名列表核对。5.2 文本渲染字体和清晰度是两个独立问题import { TextSystem, Text } from eva/plugin-renderer-text; const label new GameObject(label, { size: { width: 400, height: 80 }, position: { x: 375, y: 400 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); label.addComponent(new Text({ text: 开始游戏, style: { fontSize: 36, fontFamily: Arial, sans-serif, fill: 0xffffff, fontWeight: bold, }, }));fill用的是数字形式的颜色值不是 CSS 字符串写成#ffffff不生效。这一点跟 Canvas 原生 API 的习惯不一样容易忘。字体加载是另一回事。fontFamily里写的字体如果没在页面里加载好渲染时用的就是系统兜底字体字形和设计稿对不上。自定义字体要么在 HTML 里放font-face并预加载要么用document.fonts.load()等待字体就绪再构建场景。我一般把字体加载和资源加载放在同一个Promise.all里两边都完成再game.start()。清晰度问题单独说文字发虚通常是resolution没设或者被设成了 1。渲染器按逻辑尺寸建画布没有像素比放大在高分屏上就是一个逻辑像素铺到三个物理像素上糊是必然的。把resolution按 dpr 设上去同时确认对应TextSystem已经注册在系统列表里。5.3 事件系统的坐标系换算import { EventSystem, Event } from eva/plugin-renderer-event; const btn new GameObject(btn, { size: { width: 300, height: 120 }, position: { x: 375, y: 900 }, origin: { x: 0.5, y: 0.5 }, anchor: { x: 0.5, y: 0.5 }, }); const evt btn.addComponent(new Event()); evt.on(tap, () { console.log(点击生效); });不传area时组件默认用节点的size作为命中区域这是最常用的方式。要做异形热区传area指定矩形范围。坐标系这块有个必踩的坑渲染器做了分辨率放大之后触摸坐标和逻辑坐标不是同一个尺度。EVA 的事件系统在内部处理了这个换算但前提是你的RendererSystem参数配置正确。如果你自己在外面又套了一层 CSS 缩放比如给 canvas 设了width: 100%换算就会错位表现为点左边触发了右边。正确做法是让 canvas 的 CSS 尺寸和逻辑尺寸保持一致的比例关系缩放由渲染器统一处理不要让 CSS 和渲染器各管一套。移动端适配我一般按屏幕宽度算出缩放比然后对 canvas 元素做transform: scale()父容器再居中这样事件换算链路是干净的。6. 上线前的自查白屏、404、掉帧三类问题的排查链路6.1 白屏按四层往下剥白屏是最常见的求助我给一套固定的排查顺序从下往上剥基本十分钟内能定位。第一层看控制台有没有报错。有明确报错就先解决报错别往下走。xxx is not a constructor基本就是漏装包。第二层看 canvas 元素在不在 DOM 里。打开元素检查器找canvas。找不到说明RendererSystem根本没成功初始化回头检查参数里的canvas是不是拿到了一个null——最常见的原因是脚本在 DOM 就绪之前执行了。第三层看 canvas 的尺寸。找到元素了看它的width和height属性。如果是 0说明参数没传对。如果是750×1334这种正常值但画面还是空的往下走。第四层看场景里有没有子节点。在控制台里打印game.scene.children.length。是 0说明构建场景的代码压根没执行——大概率是上面await的地方挂了或者 Promise 没等到。不是 0说明节点在但没画出来回去查size、visible、alpha、资源的name这几项。这四层走完还白屏的话把renderType临时切成 Canvas很多时候 WebGL 上下文创建失败比如在虚拟机的无头环境里会静默黑屏切换一下立刻就能确认。6.2 打包后资源 404三种成因对应三种解法本地好、线上挂八成是资源路径。分清是哪种现象成因解法请求路径里没有 hash指向了不存在的旧文件public目录里的文件名手写错了或者部署时没同步核对public与代码里的路径是否字面一致请求路径带了错误的域名或前缀用了绝对路径/assets/x.png但应用部署在子路径下改用相对于base的路径或把base配到构建配置里请求路径是[object Object]之类url字段传的不是字符串多半是new URL()忘了取.href检查url变量类型第二种在部署到子目录时特别高发。public资源的路径要跟着构建配置的base走base改了路径前缀就得跟着改最稳的做法是用环境变量拼前缀不写死在代码里。还有一种隐蔽的图片确实 200 了但画面上没有。这时候去看响应头里的Content-Type。某些静态服务器对不认识的扩展名会返回application/octet-stream图片解析器接不住静默失败。这种情况改服务器配置或者换个文件名后缀就能验证。6.3 帧率和渲染模式别急着上 WebGL很多人默认觉得 WebGL 一定比 Canvas 快实际项目里不一定。EVA 的 Canvas 渲染器在元素数量少几十个以内、绘制区域小的情况下表现相当好启动还快。真正需要 WebGL 的是这几种场景同屏上百个半透明元素叠加、需要做滤镜和混合模式、需要高频重绘大面积区域。判断方法别靠猜装eva/plugin-stats把帧率面板挂上去看。import { StatsSystem } from eva/plugin-stats; game new Game({ systems: [ new RendererSystem({ /* ... */ }), new StatsSystem(), ], });面板上如果帧率稳定在 60别动。如果掉到 40 以下先做这三件事再考虑换渲染模式把不可见的节点visible设成 false 而不是留在场景里把长时间不变的静态内容合并到一张图上把每帧都在改的属性位置、缩放和不变的属性分开避免同一节点上挂太多组件。还有一个小技巧frameRate从 60 降到 30肉眼对静态为主的界面几乎无感但 CPU 占用能直接砍半。展示型页面我经常这么干尤其是嵌在长页面里的那种。我个人在几个项目里用下来EVA 这套东西最大的门槛不在 API而在装和配这两步——把包按层装对、把资源路径在构建工具里理顺后面写业务代码其实相当顺组件化的思路一旦建立起来加东西就是拼积木。反过来如果这两步糊弄过去了后面每加一个功能都会撞一次同样的墙。所以第一次上手别急着写功能先花二十分钟把最小组合跑通、把目录结构定下来这笔时间花得值。
