pixijs-migration-v8

此技能是一份破坏性变更清单，用于将 v7 代码库升级到 v8。请按类别从上到下逐项处理；清单将每种 v7 写法对应到 v8 的替代写法。

快速开始

安装单个包，然后按此顺序迁移：导入 → Application 初始化 → Graphics → Text → 事件 → 着色器/滤镜 → 清理。

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);

相关技能： pixijs-application（异步初始化）、pixijs-scene-graphics（新的填充/描边 API）、pixijs-custom-rendering（着色器重构）、pixijs-scene-text（Text 构造函数变更）、pixijs-performance（销毁模式）。

迁移清单：v7 到 v8

请逐项处理每个类别。每项均展示预期的 v8 写法，以及必须替换的 v7 写法。

初始化

异步 app.init() —— 预期写法：

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

错误写法：向 new Application({...}) 传递选项并同步使用。

app.canvas 替代 app.view —— app.view 会发出弃用警告。

Application 类型参数 —— 预期写法：new Application<Renderer<HTMLCanvasElement>>()。错误写法：new Application<HTMLCanvasElement>()。

导入

单个包 —— 预期写法：

import { Sprite, Application, Assets, Graphics } from "pixi.js";

错误写法：从任何已弃用的 v7 核心 @pixi/* 子包导入（见下方列表）。@pixi/sound 等补充包仍然有效，应继续使用。

已弃用的 @pixi/* 包（任何版本均不得使用）： @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。

自定义构建 —— 设置 skipExtensionImports: true，并且只导入所需扩展：

import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });

注意：仍支持 manageImports: false，但它自 8.1.6 起已被弃用；建议使用 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。

社区滤镜 —— 预期写法：import { AdjustmentFilter } from 'pixi-filters/adjustment'。错误写法：@pixi/filter-adjustment。

Graphics API

先绘制形状，再填充 —— 预期写法：

const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);

错误写法：beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()。

形状方法重命名：

v7	v8
drawRect	rect
drawCircle	circle
drawEllipse	ellipse
drawPolygon	poly
drawRoundedRect	roundRect
drawStar	star
drawRegularPolygon	regularPoly
drawRoundedPolygon	roundPoly
drawRoundedShape	roundShape
drawChamferRect	chamferRect
drawFilletRect	filletRect

Fill 替代 beginFill/beginTextureFill —— 预期写法：

graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });

错误写法：beginFill(color, alpha) 或 beginTextureFill({ texture, alpha, color })。

Stroke 替代 lineStyle —— 预期写法：

graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });

错误写法：lineStyle(2, 'white') 或 lineTextureStyle({ texture, width, color })。

孔洞使用 cut() —— 预期写法：

graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();

错误写法：beginHole() / endHole()。

GraphicsContext 替代 GraphicsGeometry —— 预期写法：

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)。

文本

Options 对象构造函数——预期：

const text = new Text({ text: "Hello", style: { fontSize: 24 } });
const bmp = new BitmapText({ text: "Hello", style: { fontFamily: "MyFont" } });
const html = new HTMLText({ text: "<b>Hello</b>", style: { fontSize: 24 } });

错误：new Text('Hello', { fontSize: 24 })（位置参数）。

位图字体加载——在调用 Assets.load('font.fnt') 前，必须先 import 'pixi.js/text-bitmap'。

精灵 / 网格

Texture.from 不再加载 URL——必须先调用 await Assets.load('image.png')，然后再调用 Texture.from('image.png')。

NineSliceSprite 取代 NineSlicePlane——预期：

const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});

Mesh 重命名： SimpleMesh -> MeshSimple、SimplePlane -> MeshPlane、SimpleRope -> MeshRope。它们都使用 options 对象。

MeshGeometry options——预期：

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

错误：new MeshGeometry(vertices, uvs, indices)。

ParticleContainer 使用 Particle——预期：

const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);

错误：container.addChild(new Sprite(texture))。

事件

eventMode 取代 interactive——预期：

sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* handle */
});

旧写法：sprite.interactive = true;（仍可作为 eventMode = 'static' 的别名使用，但建议使用明确写法）。

默认 eventMode 为 'passive'（不触发事件）。必须显式设置为 'static' 或 'dynamic'。

Ticker 回调——预期：

app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});

错误：app.ticker.add((dt) => { bunny.rotation += dt; })——可以编译，但 dt 是一个 Ticker 对象，而非数字。它会被强制转换为 NaN，导致旋转值被悄然破坏。

updateTransform 已移除——在构造函数中改用 this.onRender = this._onRender.bind(this)。

着色器

Shader.from 使用 options——预期：

const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});

错误：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 })。

Uniforms 必须指定类型——new UniformGroup({ uTime: { value: 1, type: 'f32' } })。错误：new UniformGroup({ uTime: 1 })。

纹理是资源，而非 uniforms——将其作为顶层资源条目传入（texture.source、texture.style），而不是放在 UniformGroup 中。

纹理

Sprite 不再自动检测纹理 UV 变化——如果在创建后修改纹理的 frame，请调用 texture.update() 重新计算 UV，然后调用 sprite.onViewUpdate() 刷新精灵。必须按此顺序调用这两个方法。更新源数据（例如视频纹理）仍会自动完成。

texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's display

Mipmaps——BaseTexture.mipmap 已重命名为 autoGenerateMipmaps。对于 RenderTextures，必须手动更新 mipmaps：

const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();

适配器

DOMAdapter 取代 settings.ADAPTER——预期：

import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();

错误：settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();。

内置适配器：BrowserAdapter（默认）、WebWorkerAdapter（用于 Web Worker）。

其他

已移除 DisplayObject——Container 是基类。class MyObj extends DisplayObject 会报错。

叶节点不能有子节点——Sprite、Graphics、Mesh、Text 都是叶节点。请将其包装在 Container 中。

属性已重命名（旧名称仍作为弃用别名保留，并会发出警告）：

• container.name -> container.label
• container.cacheAsBitmap = true -> container.cacheAsTexture(true)

getBounds() 返回类型已更改：getBounds() 现在返回 Bounds 对象，而不是 Rectangle。Bounds 提供 .x、.y、.width、.height getter，因此基本用法仍然可行。需要 Rectangle 实例时（例如调用 .contains()），请使用 .rectangle。

已移除 settings 对象——请使用 AbstractRenderer.defaultOptions.resolution = 1 和 DOMAdapter.set(BrowserAdapter)。

已移除 utils 命名空间——请使用 import { isMobile } from 'pixi.js'，而不是 utils.isMobile。

文本解析器重命名：

• TextFormat -> bitmapFontTextParser
• XMLStringFormat -> bitmapFontXMLStringParser
• XMLFormat -> bitmapFontXMLParser

Assets.add——Assets.add({ alias: 'bunny', src: 'bunny.png' })。错误用法：Assets.add('bunny', 'bunny.png')。

枚举常量已替换为字符串：

v7	v8
SCALE_MODES.NEAREST	'nearest'
SCALE_MODES.LINEAR	'linear'
WRAP_MODES.CLAMP	'clamp-to-edge'
WRAP_MODES.REPEAT	'repeat'
WRAP_MODES.MIRRORED_REPEAT	'mirror-repeat'
DRAW_MODES.TRIANGLES	'triangle-list'
DRAW_MODES.TRIANGLE_STRIP	'triangle-strip'
DRAW_MODES.LINES	'line-list'
DRAW_MODES.LINE_STRIP	'line-strip'
DRAW_MODES.POINTS	'point-list'

剔除需手动处理——设置 cullable = true，然后在渲染前调用 Culler.shared.cull(container, viewRect)。或者通过 extensions.add(CullerPlugin) 添加 CullerPlugin。

迁移前摘要

• 依赖中没有已弃用的 v7 核心 @pixi/* 包（@pixi/sound 等辅助包可以保留）
• 所有核心 @pixi/* 导入均已转换为 pixi.js
• 所有 new Application({...}) 均已转换为 await app.init({...})
• 所有 Graphics 代码均使用先定义形状、再填充的模式
• 所有构造函数均使用选项对象（Text、Mesh、NineSliceSprite 等）
• Shader/Filter 代码使用 {gl, resources} 模式，并使用类型化 uniforms
• ParticleContainer 代码使用 Particle，而非 Sprite
• Ticker 回调访问 ticker.deltaTime，而非将第一个参数作为 delta
• 事件处理使用 eventMode，而非 interactive
• 已移除 settings 和 utils 引用
• 已将 DisplayObject 引用替换为 Container
• 修改纹理 UV 时，在需要的地方调用 sprite.onViewUpdate()
• RenderTexture 的 mipmap 代码手动调用 source.updateMipmaps()
• 已将 settings.ADAPTER 替换为 DOMAdapter.set()

常见错误

[CRITICAL] 从已弃用的 v7 核心 @pixi/* 子包导入

错误：

import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";

正确：

import { Sprite, Application } from "pixi.js";

v8 使用单一的 pixi.js 包。v7 核心 @pixi/* 子包已弃用，不能使用（请参阅上文 Imports 下的完整列表）。@pixi/sound 等辅助包仍然有效。

[CRITICAL] 使用 DisplayObject 作为基类

错误：class MyObject extends DisplayObject { ... } 正确：class MyObject extends Container { ... }

v8 已移除 DisplayObject。Container 是所有显示对象的基类。

[HIGH] 使用旧的 SCALE_MODES/WRAP_MODES/DRAW_MODES 枚举

错误：texture.source.scaleMode = SCALE_MODES.NEAREST; 正确：texture.source.scaleMode = 'nearest';

v8 使用字符串值。旧枚举可能仍可作为弃用别名使用，但应替换。

[HIGH] 使用 interactive = true 而不是 eventMode

旧写法：sprite.interactive = true;（仍可作为 eventMode = 'static' 的别名使用） 推荐写法：sprite.eventMode = 'static';

默认 eventMode 为 'passive'（不接收事件）。必须显式设置为 'static'（可进行命中测试，不检查 tick）或 'dynamic'（可进行命中测试，并检查 tick）。interactive = true 仍可使用，且不会发出弃用警告，但 eventMode 才是 v8 的规范 API。

[HIGH] 使用 utils 命名空间

错误：import { utils } from 'pixi.js'; utils.isMobile.any(); 正确：import { isMobile } from 'pixi.js'; isMobile.any();

utils 命名空间已移除。所有实用函数都通过直接导入使用。

[HIGH] 预期纹理 UV 变化会自动更新精灵

错误：修改 texture.frame，并假定精灵会自动更新。 正确：修改纹理 UV 后，调用 sprite.onViewUpdate()。

为提升性能，精灵不再订阅纹理 UV 变化事件。源数据更新（例如视频）仍会自动反映。

API 参考

• v8 迁移指南
• v7 迁移指南
• Application
• Graphics
• Container