PixiJS v8 项目脚手架实战指南：用 create-pixi CLI 从零搭建与集成 WebGL/WebGPU 应用
【免费下载链接】pixijsThe HTML5 Creation Engine: Create beautiful digital content with the fastest, most flexible 2D WebGL renderer.项目地址: https://gitcode.com/gh_mirrors/pi/pixijs
create pixi.js是 PixiJS v8 官方提供的项目脚手架 CLI，用于在几秒钟内生成一个可直接运行的 PixiJS 工程，也支持通过npm install pixi.js向既有项目增量集成 PixiJS。本文以官方技能文档 skills/pixijs-create/SKILL.md 为主线，完整覆盖 npm/yarn/pnpm/bun 四种包管理器的创建命令、交互式与非交互式两种流程、四类模板预置的选择逻辑、脚手架后的开发脚本，并深入仓库源码验证Application的初始化链路，帮助你快速上手并避开常见的坑。
Quick Start：两条命令完成项目搭建
交互式创建一个全新 PixiJS 项目：
npm create pixi.js@latest或者在命令行直接指定项目名与模板，跳过所有提示：
npm create pixi.js@latest my-game -- --template bundler-vite随后进入项目目录、安装依赖并启动开发服务器：
cd my-game npm install npm run dev脚手架要求Node.js 18+ 或 20+。个别模板（尤其是creation-web和framework-react）可能对 Node 版本要求更高，包管理器会在检测到版本不匹配时给出 "engines" 警告，升级 Node 后重跑 CLI 即可。
向现有项目添加 PixiJS
如果项目已经配置好了打包器（Vite、Webpack、esbuild 等）或框架（React 等），不必使用 CLI，直接安装 npm 包：
npm install pixi.js然后从pixi.js导入并构造Application即可：
import { Application } from "pixi.js"; const app = new Application(); await app.init({ resizeTo: window, background: "#1099bb" }); document.body.appendChild(app.canvas);CLI 模板只是新项目的一种便捷启动方式，并没有给库本身添加任何npm install pixi.js给不了的能力——两者最终使用的是同一个pixi.js包。当前仓库的 package.json 可以印证这一点：pixi.js主包通过main: "lib/index.js"/module: "lib/index.mjs"/types: "lib/index.d.ts"暴露入口，并利用exports字段提供pixi.js/app、pixi.js/gif、pixi.js/filters等按需子路径（见 package.json），任何打包器都能直接消费。
选择包管理器：同一命令的四种写法
create pixi.js对四种主流包管理器使用相同形状的命令：
npm create pixi.js@latest yarn create pixi.js pnpm create pixi.js bun create pixi.jsnpm 7+ 有一个关键差异：在 npm 7 及更高版本中，包说明符之后的标志会被 npm 自身消费，必须用--分隔符把参数转发给 CLI，否则--template会被忽略、退回到交互式提示：
npm create pixi.js@latest my-game -- --template bundler-viteYarn、pnpm 和 bun 不需要额外的分隔符：
yarn create pixi.js my-game --template bundler-vite pnpm create pixi.js my-game --template bundler-vite bun create pixi.js my-game --template bundler-vite另外，使用.作为项目名可以把脚手架写入当前目录（见下文"在现有目录中脚手架"）。
交互式流程：跟着提示走
不带任何参数运行create pixi.js会依次弹出如下提示：
- 项目名（默认
pixi-project）； - 框架 / 模板类别；
- 变体（适用时选择 TypeScript 还是 JavaScript）；
- 是否立即安装依赖（部分运行器会询问）。
流程结束时，CLI 会打印与调用它的包管理器相对应的cd+ 安装 + dev 命令，直接复制执行即可。
非交互式流程：面向脚本与 CI
在 CI、自动化脚本或快速上手文档中，更推荐用项目名加--template跳过全部提示：
npm create pixi.js@latest my-game -- --template bundler-vite这种形式输出稳定、可重复，适合放进 Makefile、GitHub Actions 或任何流水线任务中。
可用模板预置：四类选择逻辑
模板分为四类，先明确类别再选具体预置：
- Bundler 模板（
bundler-*）：用你选择的打包器接好通用 PixiJS 工程。适合想自己决定项目结构的情况。 - Creation 模板（
creation-*）：面向平台定制的启动器，已经接好额外能力（AssetPack 资源打包、音效、UI、场景路由）。适合想要"开箱即用全家桶"的情况。 - Framework 模板（
framework-*）：把 PixiJS 嵌入宿主框架（如 React）中。 - Extension 模板（
extension-*）：用于搭建可复用的 PixiJS 扩展/包。
对大多数新项目，bundler-vite是推荐起点。完整预置列表如下：
| 模板 | 内容 |
|---|---|
bundler-vite | Vite + TypeScript PixiJS 工程，默认的首选模板 |
bundler-vite-js | Vite + 纯 JavaScript |
bundler-webpack | Webpack + TypeScript |
bundler-webpack-js | Webpack + 纯 JavaScript |
bundler-esbuild | esbuild + TypeScript |
bundler-esbuild-js | esbuild + 纯 JavaScript |
bundler-import-map | 无打包器方案，使用浏览器 import map（适合学习/演示） |
creation-web | PixiJS Creation Engine Web 模板，内置基于场景的游戏脚手架、AssetPack、音效与 UI 集成 |
framework-react | React + TypeScript + PixiJS（通过@pixi/react包） |
framework-react-js | React + 纯 JavaScript + PixiJS |
extension-default | 构建可复用 PixiJS 扩展/包的启动器 |
实时模板清单维护在create-pixi仓库；如果不确定当前有哪些选项，直接不带参数运行npm create pixi.js@latest，交互菜单会展示最新列表。
脚手架后的开发流程
每个模板都内置相同的三步上手流程：
cd my-game npm install npm run devnpm run dev会在默认端口启动本地开发服务器（Vite 默认 5173、webpack 默认 8080 等，模板自带 README 中有精确端口）。修改src/下的代码会热更新，无需整页刷新。
其余常用脚本（不同预置的名称可能略有差异）：
npm run build：在dist/生成生产构建；npm run preview/npm run serve：在本地预览生产构建；npm run lint：运行模板配置的 linter（如果模板自带了）。
仓库中的真实 Vite 工程可以印证这套工作流：playground使用 playground/vite.config.ts 配置 Vite，其中通过alias把pixi.js直接指向lib/index.mjs以便本地调试（playground/vite.config.ts），并把build.target设为esnext（playground/vite.config.ts）——这正是 Vite + PixiJS 工程的典型形态，可作为bundler-vite模板落地后的对照样本。
在现有目录中脚手架
把项目名写成.即可将脚手架写入当前工作目录：
mkdir my-game cd my-game npm create pixi.js@latest . -- --template bundler-vite注意：如果目录非空且存在与脚手架冲突的文件，CLI 会拒绝执行，除非你在确认提示中同意覆盖。
源码验证：app.init()背后发生了什么
脚手架生成的入口文件（src/main.ts）通常就是两件事：new Application()与await app.init(...)。从当前仓库源码可以完整还原这条链路。
在 src/app/Application.ts 中，Application构造函数不接受任何参数——传入选项只会触发 v8 弃用警告（src/app/Application.ts），这是 v8 相对 v7 最重要的 API 变化：
public async init(options?: Partial<ApplicationOptions>) { options = { ...options }; this.stage ||= new Container(); this.renderer = await autoDetectRenderer(options as ApplicationOptions) as R; Application._plugins.forEach((plugin) => { plugin.init.call(this, options); }); }（见 src/app/Application.ts）。也就是说：
app.stage是一个普通的Container（在 src/app/Application.ts 声明），所有场景对象都挂在它下面；app.renderer由autoDetectRenderer按preference（webgl/webgpu/canvas或数组形式）自动探测创建；- 所有注册的
ApplicationPlugin会依次以 Application 实例为this调用init，把resizeTo、autoStart、sharedTicker等选项落到实处。
默认安装的两个插件在 src/app/init.ts 中注册：ResizePlugin与TickerPlugin（src/app/init.ts）。TickerPlugin会在init完成后自动把app.render()挂到每帧循环上（对应选项autoStart: false可关闭）；ResizePlugin监听resize事件并调用renderer.resize()同步画布尺寸。
app.canvas、app.screen等属性都是对 renderer 的只读转发：canvas返回渲染器的HTMLCanvasElement（src/app/Application.ts），screen返回描述可见区域的Rectangle（src/app/Application.ts）。销毁时，插件按注册的逆序销毁，随后stage.destroy(options)与renderer.destroy(rendererDestroyOptions)（src/app/Application.ts）——这就是脚手架生成的入口在app.init()之后可以立刻使用app.canvas/app.renderer/app.screen的底层保证。
Common Mistakes：三个高频坑
[HIGH] npm 7+ 上漏写--分隔符
错误写法：
npm create pixi.js@latest my-game --template bundler-vite正确写法：
npm create pixi.js@latest my-game -- --template bundler-vite原因：npm 7+ 会消费包说明符之后的标志，除非用--转发。缺少分隔符时 CLI 会忽略--template并退回交互式提示。Yarn、pnpm、bun 不需要分隔符。
[MEDIUM] 在过旧的 Node 版本上运行
PixiJS 要求 Node 18+ 或 20+，部分模板（framework-react、creation-web）对工具链还有更高的版本预期。看到包管理器报 "engines" 警告时，先升级 Node 再重跑 CLI。
[MEDIUM] Vite 生产构建中模块顶层的await app.init()失效
在 Vite 版本<=6.0.6上，顶层await在开发环境正常，但在生产构建中会出问题，因此bundler-vite工程如果在模块顶层这样做，npm run build之后会失败：
const app = new Application(); await app.init({ resizeTo: window }); // 生产构建的模块顶层会失败把初始化包进 async IIFE 即可：
(async () => { const app = new Application(); await app.init({ resizeTo: window }); document.body.appendChild(app.canvas); })();把 Vite 升级到 6.0.6 以上也能解决，但 IIFE 写法在所有版本上都安全，并且与 PixiJS 官方快速上手指南一致。
Next Steps：脚手架之后的系统学习路径
npm run dev启动后，模板会打开一个空白或 bunny-sprite 场景。按以下顺序继续深入：
- 阅读 skills/pixijs-application/SKILL.md，理解模板入口中
new Application()+await app.init(...)的完整选项体系，以及app.stage/app.renderer/app.canvas/app.screen的关系，还有ResizePlugin、TickerPlugin的默认行为； - 阅读 skills/pixijs-core-concepts/SKILL.md 建立渲染器与渲染循环的心智模型；
- 在添加第一个有规模的场景前，阅读 skills/pixijs-scene-core-concepts/SKILL.md，提前了解"容器 vs 叶子节点"的规则；
- 需要加载真实美术资源时，通过 skills/pixijs-assets/SKILL.md 学习如何把纹理、字体和 bundle 放进模板约定的
public/或src/assets/目录。
仓库中的 examples 目录提供了大量可直接参考的运行示例（如 examples/animated-sprite_animation.ts、examples/container_blend-modes_comparison.ts、examples/graphics_basic_shapes.ts 等），它们是验证bundler-vite模板中Application用法的最佳对照资源。
【免费下载链接】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），仅供参考
