pixijs-create

create pixi.js 是用于搭建全新 PixiJS v8 项目的官方 CLI。使用任意包管理器（npm、yarn、pnpm、bun）运行它，然后从交互式菜单中选择模板，或传入 --template 跳过提示。它会生成一个独立的项目文件夹；随后进入该文件夹、安装依赖并运行开发脚本。

快速开始

通过交互式提示搭建新项目：

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；如果需要，包管理器会发出警告。

将 PixiJS 添加到现有项目

如果你已经配置好打包器、框架或项目，可以跳过 CLI，直接安装软件包：

npm install pixi.js

然后从 pixi.js 导入并构造 Application，如 pixijs-application 中所示。CLI 模板为新项目提供便利；它们不会为库添加任何 npm install pixi.js 无法提供的内容。

相关技能： pixijs-application（搭建生成的 new Application() + app.init() 入口如何工作）、pixijs-core-concepts（渲染器和渲染循环）、pixijs-scene-core-concepts（场景图基础知识，适用于你将首先添加到舞台的内容）、pixijs-assets（加载模板希望你放入 public/ 或 src/assets/ 的纹理、字体和资源包）。

核心模式

选择包管理器

所有包管理器的命令格式都相同：

npm create pixi.js@latest
yarn create pixi.js
pnpm create pixi.js
bun create pixi.js

使用 npm 7+ 时，必须在 CLI 标志前加上 --，以免 npm 将其拦截：

npm create pixi.js@latest my-game -- --template bundler-vite

Yarn、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

使用 . 作为项目名称，即可在当前目录中搭建项目。

交互流程

不带参数运行时，会逐步提示你输入：

1. 项目名称（默认为 pixi-project）。
2. 框架 / 模板类别。
3. 变体（适用时可选择 TypeScript 或 JavaScript）。
4. 是否立即安装依赖（部分运行器会提示）。

最后，CLI 会打印使用你调用它时所选包管理器对应的 cd + 安装 + 开发命令。

非交互流程

传入项目名称和 --template 即可跳过所有提示。这种形式适用于脚本、CI 和快速入门文档：

npm create pixi.js@latest my-game -- --template bundler-vite

可用的模板预设

模板分为四类：

• 打包器模板（bundler-*）：使用你选择的打包器配置的通用 PixiJS 项目。想要自行选择项目结构时，请使用这类模板。
• 创建模板（creation-*）：针对特定平台的入门模板，已配置好其他功能（AssetPack、音效、UI、场景路由）。想要开箱即用时，请使用这类模板。
• 框架模板（framework-*）：将 PixiJS 嵌入 React 等宿主框架中。
• 扩展模板（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	使用浏览器导入映射的无打包器配置（适合学习 / 演示）。
creation-web	PixiJS Creation Engine Web 模板，包含基于场景的游戏脚手架、AssetPack、音效和 UI 集成。
framework-react	通过 @pixi/react 包集成 React + TypeScript + PixiJS。
framework-react-js	React + 纯 JavaScript + PixiJS。
extension-default	用于构建可复用 PixiJS 扩展 / 包的入门模板。

可用模板列表由 create-pixi 仓库维护；如需确认当前菜单，请运行不带参数的 npm create pixi.js@latest。

脚手架生成后的流程

每个模板都提供相同的三步入门流程：

cd my-game
npm install
npm run dev

npm run dev 会在默认端口启动本地开发服务器（Vite 使用 5173，webpack 使用 8080 等；具体端口号请查看模板的 README）。修改 src/ 中的文件后会热重载，无需重新加载整个页面。

每个模板还提供以下脚本（具体名称可能因预设略有不同）：

• npm run build：在 dist/ 中生成生产构建。
• npm run preview / npm run serve：在本地运行生产构建。
• npm run lint：如果模板附带已配置的代码检查工具，则运行该工具。

在现有目录中生成脚手架

使用 . 作为项目名称，即可将文件写入当前工作目录。如果目录非空且存在冲突文件，除非你确认提示，否则 CLI 会拒绝运行。

mkdir my-game
cd my-game
npm create pixi.js@latest . -- --template bundler-vite

TypeScript 设置

PixiJS 支持 WebGPU，因此其类型声明依赖 WebGPU 类型。这些类型的来源取决于你的 TypeScript 版本。

• TypeScript 5： 未内置 WebGPU 类型，因此 PixiJS 会为你添加 @webgpu/types。无需额外设置。
• TypeScript 6 和 7： WebGPU 类型已内置于 "dom" 库中，但某些版本缺少部分类型，例如 GPUTextureUsage。请使用包含完整类型集的 @types/web 代替 "dom"。如果 types 中有 @webgpu/types，请将其移除，因为它会与内置类型冲突。

npm install --save-dev @types/web

{
  "compilerOptions": {
    "lib": ["esnext"],
    "types": ["@types/web"]
  }
}

后续步骤

运行 npm run dev 后，模板会打开一个空白场景或兔子精灵场景。通常的学习顺序如下：

1. 阅读 pixijs-application，了解模板的入口点如何创建 new Application() 并调用 await app.init(...)，app.stage / app.renderer / app.canvas 如何相互关联，以及 ResizePlugin 和 TickerPlugin 的默认行为。
2. 阅读 pixijs-core-concepts，了解渲染器和渲染循环的概念模型。
3. 在添加第一个复杂场景之前，阅读 pixijs-scene-core-concepts，提前了解容器与叶节点的规则。
4. 准备好加载实际美术资源后，通过 pixijs-assets 加载纹理。

常见错误

[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）的工具链需要更新版本的 Node。如果包管理器发出“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 }); // broken at module top level in prod

改用异步 IIFE 包装初始化代码：

(async () => {
  const app = new Application();
  await app.init({ resizeTo: window });
  document.body.appendChild(app.canvas);
})();

将 Vite 升级到 6.0.6 之后的版本也能解决此问题，但 IIFE 写法在所有版本中都安全，并且与 PixiJS 快速入门指南一致。

[HIGH] 在 TypeScript 6 或 7 的 types 中保留 @webgpu/types

错误：

{
  "compilerOptions": {
    "types": ["@webgpu/types"]
  }
}

正确：移除 "@webgpu/types" 条目，并保留其他条目。

TypeScript 6 和 7 在内置的 "dom" 库中声明了 WebGPU 类型，因此 @webgpu/types 会重复声明这些类型。当 skipLibCheck: false 时，这会在 lib.dom.d.ts 和 @webgpu/types 中产生数十个声明冲突错误。仅在 TypeScript 5 中保留它；在该版本中，PixiJS 会自动为你加载它。

[MEDIUM] TypeScript 6 或 7 中出现 Cannot find name 'GPUTextureUsage'

在 TypeScript 6.0.3 和 7.0.2 及更早版本中，内置的 "dom" 库没有 WebGPU 标志常量（GPUBufferUsage、GPUColorWrite、GPUMapMode、GPUShaderStage、GPUTextureUsage），因此使用这些常量的原始 WebGPU 代码会因 TS2552 而失败。重新添加 @webgpu/types 只有在 skipLibCheck: true 时才能通过编译，因为它会与内置类型冲突。请安装 0.0.352 或更高版本的 @types/web，从 lib 中移除 "dom"，并将 "@types/web" 与现有条目一同添加到 types 中，如TypeScript 设置所示。

[MEDIUM] moduleResolution: "node" 会导致子路径导入失败

错误：

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

正确：

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

"node"（也称为 "node10"）会忽略 PixiJS package.json 中的 exports 字段，因此 import 'pixi.js/advanced-blend-modes' 和其他子路径导入无法解析。TypeScript 6 会为这些导入报告 TS2882，并弃用此设置（TS5107）；TypeScript 7 会移除此设置（TS5108）。如果你使用打包工具，请使用 "bundler"；否则请使用 "nodenext"。

API 参考

• GitHub 上的 create-pixi
• create-pixi 文档网站
• Application：生成的入口点实例化的类。
• TypeScript 指南：TypeScript 5、6 和 7 的配置指南。