第一次装 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。少了 System，Component 就是一个没人理的数据块，挂上去也不会有任何画面。
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-hoist=true这行的意思是把依赖提升到顶层，牺牲一点隔离性换兼容性。对 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.js | Game、GameObject、resource、Transform | 永远 |
@eva/plugin-renderer | RendererSystem、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 --depth=1 | 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，而在"装"和"配"这两步——把包按层装对、把资源路径在构建工具里理顺，后面写业务代码其实相当顺，组件化的思路一旦建立起来，加东西就是拼积木。反过来，如果这两步糊弄过去了，后面每加一个功能都会撞一次同样的墙。所以第一次上手别急着写功能，先花二十分钟把最小组合跑通、把目录结构定下来，这笔时间花得值。
