先确认 Node.js ≥18，否则升级或降级 PixiJS 6；Vite 项目需设 tsconfig.json 的 "moduleResolution": "bundler" 并用具名导入；黑屏检查 DOM 插入时机、CSS 遮挡及 WebGL 上下文；HMR 时务必调用 app.destroy(true) 并清理 ticker。
npm install pixijs 失败或报错 ERR! code ERESOLVE 怎么办
多数人卡在这一步，不是引擎本身难，而是 Node.js 版本和依赖树冲突。PixiJS 7+ 要求 Node.js ≥18，但很多人本地是 v16 或 v14，npm 默认启用严格 peer 依赖检查，直接报 ERESOLVE。
- 先运行
node -v确认版本，低于v18.0.0就得升级（推荐用nvm切换，别硬改系统默认） - 如果必须用旧 Node，降级安装 PixiJS 6：
npm install pixi.js@6.5.8（6.x 对 v14/v16 兼容性好） - 临时绕过解析错误（不推荐长期用）：
npm install pixi.js --legacy-peer-deps，但后续引入@pixi/app或@pixi/graphics时可能漏依赖
用 Vite 创建 HTML5 游戏项目时，import * as PIXI from 'pixi.js' 报 Cannot find module 'pixi.js'
这是 TypeScript 类型或模块解析没对上，不是没装成功。Vite 默认不自动识别 .d.ts 入口，且 PixiJS 的 ESM 构建产物路径和类型声明不完全对齐。
- 确保
tsconfig.json中有"moduleResolution": "bundler"（Vite 项目推荐设为bundler，不是node） - 安装类型包：
npm install -D @types/pixi.js（注意：PixiJS 7+ 已内置类型，但 Vite 有时仍需显式声明） - 导入改用具名方式更稳：
import { Application, Sprite, Texture } from 'pixi.js'，避免默认导出解析失败 - 若用
create-vite模板，选vanilla-ts，别选react或vue模板后硬塞 Pixi——它们的 HMR 和 canvas 重绘容易冲突
Canvas 黑屏、Application.view 不显示，但控制台无报错
黑屏是最典型的“看起来跑起来了，其实没画进去”问题。根源常在 DOM 插入时机、CSS 样式遮挡或 WebGL 上下文丢失。
- 确认
document.body.appendChild(app.view)执行时body已存在（比如放在DOMContentLoaded回调里，或 Vite 的main.ts末尾） - 检查是否有 CSS 重置了
canvas：比如全局canvas { display: none; }或父容器height: 0，加一句app.view.style.display = 'block'快速验证 - WebGL 上下文可能被禁用（尤其某些公司内网或浏览器策略），加判断：
if (!app.renderer.gl) console.warn('WebGL not available, falling back to Canvas')；PixiJS 会自动 fallback，但 Canvas 渲染器性能差不少 - 别在
app.loader.load()完成前就调app.stage.addChild()，资源未加载完时Texture.from('xxx.png')是空的，Sprite 就不可见
热更新（HMR）下 app.destroy(true) 不彻底，多次刷新后内存暴涨
Vite 的 HMR 会保留模块状态，但 PixiJS 的 Application 实例绑定了 canvas、ticker、loader 等全局资源，不手动清理就会累积。
立即学习“前端免费学习笔记（深入）”；
- 在 HMR 接口里监听卸载：
if (import.meta.hot) import.meta.hot.dispose(() => app.destroy(true)) -
app.destroy(true)的true参数必须传，否则不会释放 WebGL 纹理和缓冲区 - 如果用了
app.ticker.add()，HMR 前要先app.ticker.remove()，否则新实例启动时老回调还在跑 - 用 Chrome DevTools 的 Memory 面板拍快照对比，重点看
WebGLTexture和ArrayBuffer数量是否随刷新递增——这是最直接的泄漏证据
事情说清了就结束。PixiJS 启动本身几行代码，但环境、构建链、渲染上下文、HMR 这几层叠在一起，任何一个环节松动都会表现为“白屏”“卡死”“越来越慢”。真正花时间的从来不是写游戏逻辑，而是让那一行 new Application() 在你机器上稳定活过三次热更新。
