本文详解如何在无构建工具的纯前端环境中正确引入 PixiJS：明确区分 CDN 全局脚本加载与 ES 模块导入的本质差异，指出直接 import * as PIXI from './pixi.js' 失败的根本原因，并提供兼顾类型提示、JSDoc 支持与零配置运行的可行方案。
本文详解如何在无构建工具的纯前端环境中正确引入 pixijs：明确区分 cdn 全局脚本加载与 es 模块导入的本质差异，指出直接 `import * as pixi from './pixi.js'` 失败的根本原因，并提供兼顾类型提示、jsdoc 支持与零配置运行的可行方案。
PixiJS 官方发布的 pixi.js（如 https://pixijs.download/release/pixi.js）是一个 IIFE（立即执行函数表达式）格式的 UMD 构建包，并非原生 ES 模块（ESM）。它默认将 PIXI 对象挂载到全局 window 对象上，因此可通过 <script></script> 标签直接加载并立即使用。但当你在 main.js 中声明 type="module" 并尝试 import * as PIXI from './pixi.js' 时，浏览器会严格按 ESM 规范解析该文件——而原始 pixi.js 文件既无 export 声明，也不符合 ESM 语法结构，导致 PIXI.Application 为 undefined，最终抛出 TypeError: PIXI.Application is not a constructor。
✅ 正确做法（零构建、兼容 JSDoc、支持智能提示）：
-
移除
type="module"，改用传统脚本顺序加载
修改index.html，将 PixiJS 作为普通<script></script>提前引入，再加载你的逻辑脚本：
<!doctype html>
<html>
<head>
<style>
body { margin: 0; overflow: hidden; }
</style>
<!-- ✅ 优先加载 PixiJS（全局注入 PIXI） -->
<script src="https://pixijs.download/release/pixi.js"></script>
<!-- ✅ main.js 普通执行，可直接访问全局 PIXI -->
<script src="main.js" defer></script>
</head>
<body></body>
</html>-
在
main.js中直接使用PIXI（无需 import）
同时，为获得完整类型支持（VS Code/JSDoc/TS 语言服务识别），可在文件顶部添加 JSDoc 类型导入注释：
/**
* @typedef {import('pixi.js').Application} PIXIApplication
* @typedef {import('pixi.js').Sprite} PIXISprite
* @type {typeof import('pixi.js')}
*/
// @ts-check
const PIXI = window.PIXI;
// ✅ 现在可安全使用，且编辑器具备完整类型提示
const app = new PIXI.Application({
width: 800,
height: 600,
backgroundColor: 0x1099bb,
antialias: true,
resolution: window.devicePixelRatio || 1,
});
document.body.appendChild(app.view);
// 示例：加载并显示小兔子
(async () => {
const texture = await PIXI.Assets.load('https://pixijs.com/assets/bunny.png');
const bunny = new PIXI.Sprite(texture);
bunny.anchor.set(0.5);
bunny.x = app.screen.width / 2;
bunny.y = app.screen.height / 2;
app.stage.addChild(bunny);
app.ticker.add(() => {
bunny.rotation += 0.01;
});
})();⚠️ 注意事项：
-
不要混用模块模式与 UMD 包：
type="module"+import只适用于真正的 ESM 包（如通过npm install pixi.js后从node_modules/pixi.js/index.mjs导入），而直接下载的pixi.js文件不是。 -
若坚持使用
import语法：唯一合规路径是搭配打包工具（Vite/Vite Plugin、esbuild、Rollup）或启用 CDN ESM 支持（例如import * as PIXI from 'https://www.php.cn/link/0cbe4bc6e48014cf92b83275100700b1@8'），但这已脱离“纯 vanilla”范畴。 -
本地离线开发建议：下载官方 ESM 构建版（如
pixi.js@8.x/dist/pixi.es.mjs）并配合type="module"使用，但需确认版本兼容性；更稳妥的做法仍是 CDN + 全局脚本加载。
总结：PixiJS 的设计哲学是“开箱即用”，其 CDN 版本专为快速原型与教学场景优化。放弃对 import 的执念，拥抱 <script></script> 顺序加载 + JSDoc 类型标注，你既能享受零配置启动、实时热更新（配合 Live Server），又能获得媲美 TypeScript 的开发体验——这才是 vanilla 环境下最高效、最健壮的入门路径。
