pixijs/pixijs-environments

pixijs-environments 是做什么的？

在标准浏览器之外（如 Web Workers、OffscreenCanvas、Node/SSR 或 CSP 受限环境）运行 PixiJS v8 时使用此技能。涵盖 DOMAdapter.set、BrowserAdapter、WebWorkerAdapter、自定义 Adapter 接口以及用于严格 CSP 的 pixi.js/unsafe-eval。触发关键词：DOMAdapter、BrowserAdapter、WebWorkerAdapter、Web Worker、OffscreenCanvas、Node、headless、SSR、CSP、unsafe-eval、Adapter。

概述

PixiJS v8 通过适配器模式（Adapter Pattern）抽象了底层平台差异，使得渲染引擎可以在不同运行环境中工作。核心接口是 DOMAdapter，通过 DOMAdapter.set() 方法可以切换不同的适配器实现。

适配器类型

BrowserAdapter

• 用途: 标准浏览器环境（默认）
• 实现: 使用 DOM API（如 document、window、HTMLCanvasElement）
• 场景: 普通 HTML 页面中的 PixiJS 渲染

WebWorkerAdapter

• 用途: Web Worker 或 OffscreenCanvas 环境
• 实现: 使用 OffscreenCanvas 和 WorkerGlobalScope，不依赖 DOM
• 场景: 后台线程渲染、跨线程页面、性能隔离
• 注意: 需要浏览器支持 OffscreenCanvas

自定义 Adapter

• 用途: Node.js、SSR（服务端渲染）或其他无 DOM 环境
• 实现: 使用 canvas 或 skia-canvas 等 Node 图形库模拟 DOM 接口
• 场景: 服务端生成纹理、截图测试、无头浏览器

使用方式

切换适配器

import { DOMAdapter } from 'pixi.js';
import { WebWorkerAdapter } from 'pixi.js';

// 在 Web Worker 中切换
DOMAdapter.set(WebWorkerAdapter);

// 或使用自定义适配器
import { MyCustomAdapter } from './my-adapter';
DOMAdapter.set(MyCustomAdapter);

CSP 严格环境

当内容安全策略（CSP）禁止 eval 时，需使用 pixi.js/unsafe-eval 入口：

// 替代默认的 'pixi.js'
import { Application } from 'pixi.js/unsafe-eval';

此入口移除了对 eval 的依赖，兼容严格的 CSP 规则（如 script-src 'self'）。

常见问题

OffscreenCanvas 支持

确保目标浏览器支持 OffscreenCanvas。不支持时降级到标准 Canvas。

Node 环境设置

在 Node.js 中需要安装额外的图形库（如 canvas），并实现 DOMAPI 接口。推荐使用社区适配器库。

调试提示

• 在 Web Worker 中，PixiJS 不提供自动 requestAnimationFrame，需手动调度渲染循环
• 确保适配器正确实现了所有必需的 DOM 方法（如 createCanvas、getCanvasRenderingContext2D）

参考资源

• PixiJS v8 官方文档 - 环境适配
• pixi.js/unsafe-eval 说明
• WebWorkerAdapter 源码