PixiJS Next.js 15 全面教程：常用 API 串联与实战指南-平芜编程栈

大家好，我是jobleap.cn的小九。
你希望掌握Node.js生态下PixiJS库的常用用法，同时获取一份基于Next.js 15整合PixiJS的详细教程，要求串联PixiJS的核心常用API并落地成可运行的实战案例。

一、前置准备

1. 环境要求

Node.js 20+（Next.js 15最低兼容版本）
npm/pnpm/yarn（推荐pnpm，性能更优）
基础JavaScript/React知识

2. 项目初始化

# 创建Next.js 15项目npx create-next-app@15 pixi-next-tutorialcdpixi-next-tutorial# 安装PixiJS依赖npminstallpixi.js# 或 pnpm add pixi.js / yarn add pixi.js

二、核心原理：Next.js+PixiJS的关键注意事项

PixiJS是客户端渲染的2D图形库，依赖浏览器DOM/Canvas API，而Next.js 15默认服务端渲染（SSR）。因此必须：

用'use client'标记组件为客户端组件
在useEffect（组件挂载后）初始化PixiJS，避免服务端执行DOM相关代码

三、完整实战：串联PixiJS核心API

我们将创建一个客户端组件，整合PixiJS所有高频API：应用创建、容器管理、图形绘制、精灵加载、文本渲染、交互事件、动画循环、滤镜、资源加载与清理。

步骤1：创建PixiJS客户端页面组件

在app目录下新建pixi-scene/Page.tsx（Next.js 15 app router的路由页面）：

// app/pixi-scene/Page.tsx 'use client'; // 关键：标记为客户端组件，禁止服务端执行 import { useEffect, useRef } from 'react'; import * as PIXI from 'pixi.js'; export default function PixiScenePage() { // 挂载Pixi画布的DOM容器Ref const canvasContainerRef = useRef<HTMLDivElement>(null); // 存储Pixi应用实例，避免重复初始化 const appRef = useRef<PIXI.Application | null>(null); useEffect(() => { if (!canvasContainerRef.current || appRef.current) return; // ========== 1. 核心API：创建PIXI应用实例 ========== const app = new PIXI.Application({ width: 800, // 画布宽度 height: 600, // 画布高度 backgroundColor: 0x1099bb, // 背景色（16进制） resolution: window.devicePixelRatio || 1, // 高清屏适配 autoDensity: true, // 自动适配像素密度 }); appRef.current = app; // 将Pixi画布挂载到DOM canvasContainerRef.current.appendChild(app.view as HTMLCanvasElement); // ========== 2. 容器API：Container（层级管理） ========== // Container类似HTML的div，用于分组管理显示对象 const mainContainer = new PIXI.Container(); app.stage.addChild(mainContainer); // stage是Pixi的根容器 // ========== 3. 绘图API：Graphics（矢量图形） ========== // 绘制红色半透明矩形 const rect = new PIXI.Graphics(); rect.beginFill(0xff0000); // 填充色 rect.drawRect(50, 50, 100, 100); // x,y,宽,高 rect.endFill(); rect.alpha = 0.7; // 透明度（0-1） mainContainer.addChild(rect); // 绘制绿色圆形 const circle = new PIXI.Graphics(); circle.beginFill(0x00ff00); circle.drawCircle(200, 100, 50); // x,y,半径 circle.endFill(); mainContainer.addChild(circle); // ========== 4. 文本API：Text（文字渲染） ========== const text = new PIXI.Text('PixiJS + Next.js 15', { fontFamily: 'Arial', fontSize: 32, fill: 0xffffff, // 文字颜色 stroke: 0x000000, // 描边颜色 strokeThickness: 2, // 描边宽度 }); text.x = 300; text.y = 50; mainContainer.addChild(text); // ========== 5. 资源加载API：Loader（加载图片） ========== app.loader.add('bunny', 'https://pixijs.io/examples/examples/assets/bunny.png') .load((loader, resources) => { // ========== 6. 精灵API：Sprite（位图渲染） ========== const bunny = new PIXI.Sprite(resources.bunny.texture); // 精灵基础属性配置 bunny.x = 400; bunny.y = 200; bunny.anchor.set(0.5); // 锚点设为中心（方便旋转/拖拽） bunny.scale.set(2); // 缩放2倍 bunny.interactive = true; // 开启交互 bunny.buttonMode = true; // 鼠标悬停显示手型 mainContainer.addChild(bunny); // ========== 7. 交互API：Pointer事件（点击/拖拽） ========== // 点击变色 bunny.on('pointerdown', () => { bunny.tint = 0xff00ff; // 品红色 }); // 松开恢复 bunny.on('pointerup', () => { bunny.tint = 0xffffff; }); // 拖拽功能 bunny.on('pointerdown', (e: PIXI.FederatedPointerEvent) => { bunny.dragging = true; bunny.data = e; bunny.alpha = 0.8; }); bunny.on('pointerup', () => { bunny.dragging = false; bunny.data = null; bunny.alpha = 1; }); bunny.on('pointerupoutside', () => { bunny.dragging = false; bunny.data = null; bunny.alpha = 1; }); bunny.on('pointermove', () => { if (bunny.dragging && bunny.data) { const newPos = bunny.data.getLocalPosition(mainContainer); bunny.x = newPos.x; bunny.y = newPos.y; } }); // ========== 8. 滤镜API：Filter（视觉效果） ========== const blurFilter = new PIXI.filters.BlurFilter(); blurFilter.blur = 0; bunny.filters = [blurFilter]; // 悬停添加模糊 bunny.on('pointerover', () => { bunny.isHovered = true; }); bunny.on('pointerout', () => { bunny.isHovered = false; }); // ========== 9. 动画API：Ticker（帧循环） ========== // Ticker替代requestAnimationFrame，delta保证帧率无关 app.ticker.add((delta) => { rect.rotation += 0.01 * delta; // 矩形旋转 // 圆形缩放动画 circle.scale.x = Math.sin(Date.now() / 1000) + 1.5; circle.scale.y = Math.sin(Date.now() / 1000) + 1.5; // 兔子悬停模糊动画 if (bunny.isHovered) { blurFilter.blur = Math.min(blurFilter.blur + 0.1, 5); } else { blurFilter.blur = Math.max(blurFilter.blur - 0.1, 0); } }); }); // ========== 10. 适配API：窗口缩放响应 ========== const handleResize = () => { if (appRef.current) { appRef.current.renderer.resize( window.innerWidth * 0.8, window.innerHeight * 0.8 ); } }; window.addEventListener('resize', handleResize); // ========== 资源清理：避免内存泄漏 ========== return () => { window.removeEventListener('resize', handleResize); if (appRef.current) { appRef.current.destroy(true); // 销毁应用+释放所有资源 appRef.current = null; } }; }, []); return ( <div style={{ width: '100vw', height: '100vh', display: 'flex', justifyContent: 'center', alignItems: 'center' }}> <div ref={canvasContainerRef}></div> </div> ); }

步骤2：运行与验证

npmrun dev# 启动后访问 http://localhost:3000/pixi-scene

你将看到：

800x600蓝色画布，适配窗口缩放
红色旋转矩形 + 绿色缩放圆形
白色带黑边的标题文字
可拖拽、点击变色、悬停模糊的兔子精灵

步骤3：拓展常用API（可选）

1. 位图文本（BitmapText）：高性能文字渲染

// 需提前准备字体位图文件（.fnt + .png） app.loader.add('gameFont', 'assets/game-font.fnt').load((loader, res) => { const bitmapText = new PIXI.BitmapText('游戏得分：100', { fontName: 'GameFont', fontSize: 48, }); bitmapText.x = 500; bitmapText.y = 50; mainContainer.addChild(bitmapText); });

2. 粒子容器（ParticleContainer）：高性能批量渲染

// 适合粒子效果/大量精灵 const particleContainer = new PIXI.ParticleContainer(1000, { scale: true, position: true, alpha: true, }); // 生成1000个随机粒子 for (let i = 0; i < 1000; i++) { const dot = new PIXI.Sprite(PIXI.Texture.WHITE); dot.x = Math.random() * 800; dot.y = Math.random() * 600; dot.scale.set(0.1); dot.tint = Math.random() * 0xffffff; particleContainer.addChild(dot); } mainContainer.addChild(particleContainer);

3. 遮罩（Mask）：区域裁剪

// 圆形遮罩，只显示兔子圆形区域内的部分 const mask = new PIXI.Graphics(); mask.drawCircle(400, 200, 80); mainContainer.addChild(mask); bunny.mask = mask;

总结

Next.js 15整合PixiJS的核心是'use client'标记+useEffect初始化，避免服务端执行DOM代码。
PixiJS高频API核心链路：Application（入口）→ Container（管理）→ Graphics/Sprite/Text（渲染）→ Loader（加载）→ Ticker（动画）→ 交互事件+滤镜（交互/视觉）。
生产环境需注意资源清理（destroy）、高性能渲染（ParticleContainer）、窗口适配，避免内存泄漏。