PixiJS v8 迁移实战指南从 v7 到 v8 的破坏性变更清单与代码改造手册【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs本指南基于 PixiJS 仓库中 v8 迁移 Skillskills/pixijs-migration-v8/SKILL.md与官方迁移文档src/docs/migrations/v8.md系统梳理从 v7 升级到 v8 时所有必须关注的破坏性变更异步初始化、单一pixi.js包、Graphics 的先造型后填充范式、纹理/着色器体系重构等。读完本文你将掌握一份可直接对照执行的迁移检查清单能把存量 v7 代码逐项改写成符合 v8 规范、可在 WebGL/WebGPU 双后端下运行的新代码。迁移前先判断要不要升v8 引入了 WebGPU 渲染后端整体性能与架构有大幅提升但破坏性变更同样显著。升级前先问自己一个问题项目依赖的第三方 Pixi 生态库是否已经迁移到 v8官方迁移文档列出的生态状态如下已迁移Filters、Sound、Gif、Storybook、UI、Open Games迁移中React、Spine待迁移Pixi layers官方倾向直接并入 v8 核心而非单独迁移。若你的项目重度依赖尚未迁移的库建议暂缓升级纯 Pixi 项目则可以直接动手。升级顺序建议为导入语句 → Application 初始化 → Graphics → Text → 事件 → 着色器/滤镜 → 收尾清理。快速上手最小可运行的 v8 应用import { Application, Graphics } from pixi.js; const app new Application(); await app.init({ width: 800, height: 600 }); document.body.appendChild(app.canvas); const g new Graphics() .rect(0, 0, 100, 100) .fill({ color: 0xff0000 }) .stroke({ width: 2, color: 0x000000 }); app.stage.addChild(g);注意与 v7 的关键差异new Application()不再接受配置对象、必须await app.init(...)画布挂载使用app.canvas而非app.viewGraphics 采用先画形状、再填充/描边的链式调用。这一点在 Application 源码 中有明确佐证构造函数中传入 options 会触发deprecation警告Application constructor options are deprecated, please use Application.init() instead而init()内部通过autoDetectRenderer异步创建渲染器。初始化异步化与类型参数必须 await app.init()v8 引入 WebGPU 渲染器后渲染器的创建变成了异步操作init()返回 Promise。错误写法是把 options 传给构造函数并同步使用正确写法如下const app new Application(); await app.init({ width: 800, height: 600 }); document.body.appendChild(app.canvas);从 Application.init 实现 可以看到它先autoDetectRenderer(options)异步创建渲染器再依次执行已注册的 Application 插件如 TickerPlugin、ResizePlugin、CullerPlugin。这也是为什么app.ticker、app.renderer等属性只有在await init()之后才可用。app.canvas 取代 app.viewapp.view依然存在但会打印弃用警告见 Application 源码请统一改用app.canvas。传入自定义画布的方式也变为await app.init({ view: document.createElement(canvas) })。泛型参数改为 Renderer 类型v7 中new ApplicationHTMLCanvasElement()在 v8 不再正确因为泛型描述的不再是视图类型而是渲染器类型以保证app.renderer的类型推断准确// WebGL 或 WebGPU自动检测 const app new ApplicationRendererHTMLCanvasElement(); // 强制 WebGL const app new ApplicationWebGLRendererHTMLCanvasElement(); // 强制 WebGPU const app new ApplicationWebGPURendererHTMLCanvasElement();初始化参数速查ApplicationOptions支持渲染、性能、自适应缩放等配置常用项如下完整定义见 Application 源码选项说明width/height画布宽高像素backgroundColor背景色如0x1099bbantialias是否开启抗锯齿resolution分辨率/设备像素比常设window.devicePixelRatiopreference渲染后端webgl、webgpu、canvas或数组powerPreferenceGPU 电源偏好如high-performanceautoStart是否自动启动渲染循环sharedTicker是否使用共享 TickerresizeTo/autoDensity自动缩放与 DPR 适配skipExtensionImports是否跳过默认扩展的自动导入自定义构建用导入从 pixi/* 子包回归单一 pixi.js 包单一包结构自 v5 起 PixiJS 采用多子包结构但多版本共存容易引发内部缓存冲突。v8 回归单一包// v7 旧写法 import { Application } from pixi/app; import { Sprite } from pixi/sprite; // v8 新写法 import { Application, Sprite } from pixi.js;以下 v7 核心子包在任何版本下都禁止再使用补充性生态包如pixi/sound不受影响可继续使用pixi/accessibility、pixi/app、pixi/assets、pixi/compressed-textures、pixi/core、pixi/display、pixi/events、pixi/extensions、pixi/extract、pixi/filter-alpha、pixi/filter-blur、pixi/filter-color-matrix、pixi/filter-displacement、pixi/filter-fxaa、pixi/filter-noise、pixi/graphics、pixi/mesh、pixi/mesh-extras、pixi/mixin-cache-as-bitmap、pixi/mixin-get-child-by-name、pixi/mixin-get-global-position、pixi/particle-container、pixi/prepare、pixi/sprite、pixi/sprite-animated、pixi/sprite-tiling、pixi/spritesheet、pixi/text、pixi/text-bitmap、pixi/text-html。自定义构建与扩展导入v8 通过扩展extensions系统为渲染器按需装配能力。默认情况下以下扩展会被自动导入accessibility、app、events、filters、sprite-tiling、text、text-bitmap、text-html、graphics、mesh、sprite-nine-slice。若想完全控制包体积可设置skipExtensionImports: true并手动按需导入import pixi.js/graphics; import pixi.js/text; import pixi.js/events; import { Application } from pixi.js; const app new Application(); await app.init({ skipExtensionImports: true });从 AbstractRenderer 初始化逻辑 可以看到skipExtensionImports true或旧选项manageImports false时渲染器会跳过环境扩展加载与默认 loader 注册。注意manageImports: false自 8.1.6 起标记为deprecated定义见 SharedSystems.ts一律改用skipExtensionImports: true。即便开启默认自动导入以下扩展也必须显式手动导入pixi.js/advanced-blend-modes、pixi.js/unsafe-eval、pixi.js/prepare、pixi.js/math-extras、pixi.js/dds、pixi.js/ktx、pixi.js/ktx2、pixi.js/basis。还有一个易踩的坑pixi.js/text-bitmap会额外注册 Assets 加载能力。如果要在渲染器初始化之前加载位图字体必须先导入它import pixi.js/text-bitmap; import { Assets, Application } from pixi.js; await Assets.load(my-font.fnt); // 未导入 text-bitmap 则此步无法加载 await new Application().init();社区滤镜pixi/filter-*系列包在 v8 下不再维护改为从pixi-filters子模块直接导入import { AdjustmentFilter } from pixi-filters/adjustment; // 而非 pixi/filter-adjustmentGraphics先造型、后填充shape-then-fillGraphics 是 v8 改动最大的 API。先 beginFill 再画形状的旧流程被彻底反转——先画出形状再对上一个形状执行fill/stroke/cut。// v7 旧写法 const g new Graphics().beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill(); // v8 新写法 const g new Graphics().rect(50, 50, 100, 100).fill(0xff0000);形状方法更名对照表v7v8drawRectrectdrawCirclecircledrawEllipseellipsedrawPolygonpolydrawRoundedRectroundRectdrawStarstardrawRegularPolygonregularPolydrawRoundedPolygonroundPolydrawRoundedShaperoundShapedrawChamferRectchamferRectdrawFilletRectfilletRectfill 取代 beginFill / beginTextureFillfill接受颜色或FillStyle选项对象同时替代了beginFill与beginTextureFillgraphics .rect(0, 0, 100, 100) .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });stroke 取代 lineStyle / lineTextureStylegraphics.rect(0, 0, 100, 100).fill(blue).stroke({ width: 2, color: white }); // 纹理描边 graphics .rect(0, 0, 100, 100) .stroke({ texture: Texture.WHITE, width: 10, color: 0xff0000 });lineStyle(2, white)、lineTextureStyle({...})均告废弃。镂空用 cut()beginHole()/endHole()被cut()取代同样作用于前一个形状graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();GraphicsContext 取代 GraphicsGeometryv8 把绘图指令抽到独立的GraphicsContext多个Graphics可共享同一份上下文数据复用更高效const context new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000); const g1 new Graphics(context); const g2 new Graphics(context);旧写法new Graphics(graphics.geometry)已失效。仓库中大量示例采用新范式可参考 graphics_basic_shapes.ts 与 graphics_fill_stroke_gradient.ts 等示例文件的实际用法。Text构造器全部改为选项对象v7 的位置参数构造new Text(Hello, style)在 v8 一律改为单一 options 对象const text new Text({ text: Hello, style: { fontSize: 24 } }); const bmp new BitmapText({ text: Hello, style: { fontFamily: MyFont } }); const html new HTMLText({ text: bHello/b, style: { fontSize: 24 } });加载位图字体前必须import pixi.js/text-bitmap见上文自定义构建一节。其余受影响构造器同理BlurFilter({ blur, quality, resolution, kernelSize })、DisplacementFilter({ sprite, scale })、PlaneGeometry({ width, height, verticesX, verticesY })、TileSprite({ texture, width, height })等全部改为对象入参。Sprites 与 MeshTexture.from 不再自动加载 URLv8 中纹理不再自行管理资源加载Texture.from只接受已加载的资源或已通过Assets.load注册的字符串await Assets.load(image.png); // 必须先加载 const texture Texture.from(image.png);NineSliceSprite 取代 NineSlicePlaneconst ns new NineSliceSprite({ texture, leftWidth: 10, topHeight: 10, rightWidth: 10, bottomHeight: 10, });Mesh 类更名 选项对象SimpleMesh→MeshSimpleSimplePlane→MeshPlaneSimpleRope→MeshRope全部使用选项对象构造MeshGeometry由位置参数改为对象positions、uvs、indices、topologyconst geom new MeshGeometry({ positions: vertices, uvs, indices, topology: triangle-list, });ParticleContainer 改用 Particlev8 的粒子容器不再接受 Sprite 子节点而是接收实现了IParticle接口x、y、scaleX、scaleY、anchorX、anchorY、rotation、color、texture的轻量Particle对象。粒子不进入场景图的children数组而是存储在扁平列表particleChildren中因此容器不再自算边界需要你显式提供boundsAreaconst container new ParticleContainer({ boundsArea: new Rectangle(0, 0, 800, 600), }); for (let i 0; i 100000; i) { const particle new Particle(texture); container.addParticle(particle); }由于省去了 Sprite 的冗余属性与事件粒子渲染数量上限大幅提升。相关示例见 particle-container_basic.ts。事件系统eventMode 取代 interactiveeventMode / cursorv8 默认eventMode为passive不接收任何事件必须显式设为static可命中测试不做 tick 检查或dynamic可命中测试且带 tick 检查。sprite.interactive true仍然作为eventMode static的别名可用但推荐使用规范写法sprite.eventMode static; sprite.cursor pointer; sprite.on(pointertap, () { /* handle */ });默认值passive在 EventSystem 源码 中有直接实现EventSystem._defaultEventMode options.eventMode ?? passive。事件系统的完整行为可查阅 src/events/EventBoundary.ts 与事件相关 Skillskills/pixijs-events/SKILL.md。Ticker 回调参数是 Ticker 实例v8 中ticker.add的回调第一个参数从增量时间数值改为Ticker实例app.ticker.add((ticker) { bunny.rotation ticker.deltaTime; });高危陷阱旧写法app.ticker.add((dt) { bunny.rotation dt; })能通过编译但dt实际是Ticker对象参与数值运算会被强转为NaN导致旋转值被静默污染。updateTransform 被移除节点不再承载渲染逻辑updateTransform覆写模式失效。自定义每帧逻辑请改在构造器中绑定onRenderclass MySprite extends Sprite { constructor() { super(); this.onRender this._onRender.bind(this); } _onRender() { // do custom logic } }着色器与滤镜{ gl, resources } 资源体系v8 需要同时兼容 WebGL 与 WebGPU 着色器构造方式全面重构。核心变化是纹理不再是 uniform而是作为顶层resources条目传入texture.source、texture.styleuniform 必须显式声明类型。Shader.fromconst shader Shader.from({ gl: { vertex: vertexSrc, fragment: fragmentSrc }, resources: { myUniforms: new UniformGroup({ uTime: { value: 0, type: f32 } }), }, });同时提供gpu字段含entryPoint与 WGSL 源码即可实现双后端。旧写法Shader.from(vertex, fragment, uniforms)已废弃。Filter 构造const filter new Filter({ glProgram: GlProgram.from({ fragment, vertex }), resources: { filterUniforms: { uTime: { value: 0, type: f32 } } }, });旧写法new Filter(vertex, fragment, { uTime: 0 })失效。UniformGroup 需要类型const uniformGroup new UniformGroup({ uTime: { value: 1, type: f32 }, }); uniformGroup.uniforms.uTime 100;new UniformGroup({ uTime: 1 })这种不带type的写法不再合法。仓库中的自定义着色器示例mesh_custom_shader_geometry、filters_custom-shader_glsl以及 skills/pixijs-custom-rendering/SKILL.md 提供了完整的双后端着色器实战参考。纹理TextureSource 体系与手动更新BaseTexture → TextureSourcev7 的BaseTexture在 v8 中不复存在取而代之的是一组职责更单一的 TextureSource纹理源 纹理设置 上传/使用方式TextureSource通用纹理源可自由渲染或上传主要用于 RenderTextureImageSource承载 ImageBitmap / HTMLImageElement 等图像资源CanvasSource承载 canvas主要用于 canvas 渲染WebGPUVideoSource承载视频自动保持 GPU 纹理与视频帧同步BufferSource承载任意 buffer需保证 buffer 类型与格式兼容CompressedSource处理 GPU 压缩纹理格式。手动创建纹理源的示例如下const image new Image(); image.onload function () { const source new ImageSource({ resource: image }); const texture new Texture({ source }); }; image.src myImage.png;日常使用中Assets.load返回的依然是Texture直接使用即可。精灵不再自动响应纹理 UV 变化出于性能考虑频繁换纹理时事件订阅/解绑开销不可接受v8 的 Sprite 不再订阅纹理 UV 变更事件。若修改了纹理 frame必须依次调用texture.update()重算 UV再调用sprite.onViewUpdate()刷新精灵显示两者缺一不可更新纹理源数据如视频纹理则仍会自动生效texture.frame.width texture.frame.width / 2; texture.update(); // 先重算纹理 UV sprite.onViewUpdate(); // 再刷新精灵显示Mipmap 手动管理BaseTexture.mipmap更名为autoGenerateMipmaps。RenderTexture 的 mipmap 不再自动更新需要在渲染后手动调用source.updateMipmaps()const rt RenderTexture.create({ width: 100, height: 100, autoGenerateMipmaps: true, }); renderer.render({ target: rt, container: scene }); rt.source.updateMipmaps();适配器DOMAdapter 取代 settings.ADAPTERv8 移除了全局settings对象环境适配改用静态类DOMAdapter。内置两个适配器BrowserAdapter默认与WebWorkerAdapterWeb Worker 环境import { DOMAdapter, WebWorkerAdapter } from pixi.js; DOMAdapter.set(WebWorkerAdapter); DOMAdapter.get().createCanvas();settings.ADAPTER WebWorkerAdapter; settings.ADAPTER.createCanvas()的旧写法失效。浏览器环境适配器实现见 src/environment-browser/BrowserAdapter.tsWeb Worker 版本见 src/environment-webworker/WebWorkerAdapter.ts。其他破坏性变更汇总DisplayObject 被移除Container成为所有显示对象的基类class MyObj extends DisplayObject编译失败叶子节点不能有子节点Sprite、Graphics、Mesh、Text均为叶子节点需要子节点时用Container包裹属性更名旧名保留为带警告的弃用别名container.name→container.labelcontainer.cacheAsBitmap true→container.cacheAsTexture(true)getBounds() 返回类型变化现在返回Bounds对象而非Rectangle。Bounds自带.x/.y/.width/.heightgetter基础用法不受影响需要Rectangle实例如调用.contains()时改用getBounds().rectanglesettings 对象移除改为AbstractRenderer.defaultOptions.resolution 1、DOMAdapter.set(BrowserAdapter)也可在init/autoDetectRenderer时直接传resolution、failIfMajorPerformanceCaveat等选项utils 命名空间移除import { utils } from pixi.js; utils.isMobile.any()→import { isMobile } from pixi.js; isMobile.any()文本解析器更名TextFormat→bitmapFontTextParserXMLStringFormat→bitmapFontXMLStringParserXMLFormat→bitmapFontXMLParserAssets.add 签名变化Assets.add(bunny, bunny.png)→Assets.add({ alias: bunny, src: bunny.png })枚举常量替换为字符串v7v8SCALE_MODES.NEARESTnearestSCALE_MODES.LINEARlinearWRAP_MODES.CLAMPclamp-to-edgeWRAP_MODES.REPEATrepeatWRAP_MODES.MIRRORED_REPEATmirror-repeatDRAW_MODES.TRIANGLEStriangle-listDRAW_MODES.TRIANGLE_STRIPtriangle-stripDRAW_MODES.LINESline-listDRAW_MODES.LINE_STRIPline-stripDRAW_MODES.POINTSpoint-list剔除Culling改为手动设置container.cullable true渲染前调用Culler.shared.cull(container, viewRect)需要模拟旧自动行为时通过extensions.add(CullerPlugin)注册插件。相关属性还包括cullArea与cullableChildren实现见 src/culling/Culler.ts。迁移完成度自检清单逐项核对全部通过即可认为迁移完成依赖中不再存在 v7 核心pixi/*包补充包如pixi/sound允许保留所有核心pixi/*导入已改为pixi.js所有new Application({...})已改为await app.init({...})所有 Graphics 代码采用先造型后填充模式所有构造器使用选项对象Text、Mesh、NineSliceSprite 等Shader/Filter 代码使用{ gl, resources }模式并带类型化 uniformParticleContainer 使用Particle而非SpriteTicker 回调通过ticker.deltaTime取增量而非把首个参数当数值事件处理使用eventMode而非interactivesettings与utils引用已清除DisplayObject引用全部替换为Container纹理 UV 修改处调用了sprite.onViewUpdate()RenderTexture 的 mipmap 代码手动调用source.updateMipmaps()settings.ADAPTER已替换为DOMAdapter.set()常见错误速查[严重] 从废弃的 v7 核心子包导入// 错误 import { Sprite } from pixi/sprite; import { Application } from pixi/app; // 正确 import { Sprite, Application } from pixi.js;[严重] 用 DisplayObject 作基类// 错误 class MyObject extends DisplayObject { /* ... */ } // 正确 class MyObject extends Container { /* ... */ }[高] 沿用旧枚举 SCALE_MODES / WRAP_MODES / DRAW_MODES// 错误 texture.source.scaleMode SCALE_MODES.NEAREST; // 正确 texture.source.scaleMode nearest;旧枚举可能仍作为弃用别名工作但应全部替换为字符串值。[高] 用 interactive true 代替 eventModeinteractive true依旧作为eventMode static的别名且无弃用警告但eventMode才是 v8 规范 API。默认值passive意味着不显式设置就收不到任何事件。[高] 使用 utils 命名空间// 错误 import { utils } from pixi.js; utils.isMobile.any(); // 正确 import { isMobile } from pixi.js; isMobile.any();[高] 指望纹理 UV 变化自动更新精灵修改texture.frame后必须调用sprite.onViewUpdate()纹理源数据更新如视频仍自动反映。进一步阅读官方 v8 迁移文档src/docs/migrations/v8.md本文的完整权威依据应用初始化细节skills/pixijs-application/SKILL.md 与 Application 源码Graphics 新 APIskills/pixijs-scene-graphics/SKILL.md 及 graphics_fill_stroke_gradient.ts着色器改造skills/pixijs-custom-rendering/SKILL.md 与 mesh_custom_shader_geometry纹理与资源系统skills/pixijs-assets/SKILL.md销毁与性能模式skills/pixijs-performance/SKILL.md【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
