tsParticles Engine 版本演进全解：从 2.0 模块化拆分到 4.x 渲染体系重构

tsParticles Engine 版本演进全解：从 2.0 模块化拆分到 4.x 渲染体系重构

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles

@tsparticles/engine是 tsParticles 整个生态的核心引擎包，所有 bundle、插件、shape、updater 包都依赖它。它的版本记录文件 engine/CHANGELOG.md 完整追踪了从 1.x 到当前 4.3.3 的全部发布历史，遵循 Conventional Commits 规范组织（fix/feat/BREAKING CHANGES分类）。本文以这份 CHANGELOG 为骨架，结合当前仓库中的引擎源码，梳理各主线版本的关键特性、破坏性变更与修复内容，帮助你在升级引擎时准确判断影响面，并理解 4.x 引入的绘制层（Draw Layer）、HDR 精度、粒子修改器（Modifier）等新架构在代码中的真实形态。

一、当前版本基线：4.3.3 及其发布节奏

当前仓库中 engine/package.json 声明的版本为4.3.3，与 CHANGELOG 顶部条目一致。近期发布节奏如下（全部摘自 engine/CHANGELOG.md）：

一个值得注意的细节：CHANGELOG 中大量条目标注Note: Version bump only for package @tsparticles/engine，说明该仓库是多包（monorepo）工程，当其他包（如 plugins、shapes）发布带变更的版本时，engine 会跟随版本号联动提升但无自身功能变化。阅读时可以直接跳过这类条目。

引擎的安装方式在 engine/README.md 中有说明：

npm install @tsparticles/engine # 或 yarn add / pnpm install

初始化与加载插件的基本用法（来自 engine/README.md）：

import { tsParticles } from "@tsparticles/engine"; import { loadSlim } from "@tsparticles/slim"; // 或其他 bundle await loadSlim(tsParticles); // 先加载预设特性 await tsParticles.load({ id: "tsparticles", options: { particles: { number: { value: 80 }, move: { enable: true, speed: 2 }, }, }, });

README 同时给出了两条与版本行为强相关的注意事项：插件必须在tsParticles.load()之前加载，以及某些 shape/updater 需要其对应的独立包。这两点在 2.x 拆分插件后是长期约束，也是很多升级问题的根源。

二、4.3.0：渲染管线的四大核心特性

4.3.0（2026-06-27）是 4.x 中信息量最大的版本，CHANGELOG 记录了四项feat与两项deepExtend修复。逐项对照当前源码，可以看到它们都已落在引擎的核心目录中。

2.1 新的绘制层系统（Draw Layer System）

CHANGELOG 条目为added new draw layer system。从源码结构看，它体现为 engine/src/Enums/DrawLayer.ts 中定义的固定序号层：

export enum DrawLayer { BackgroundElement = 0, // 自动绘制 background.element（CSS 背景元素） BackgroundDraw = 1, // 执行 background.draw(ctx, delta) 自定义回调 BackgroundMask = 2, // 背景遮罩（BackgroundMask 插件的 canvasPaint） CanvasSetup = 3, // 插件绘制前的画布状态配置（zoom、blend 等） PluginContent = 4, // 绘制在粒子背后的插件内容 Particles = 5, // 粒子本体渲染（按 z 分桶） CanvasCleanup = 6, // 绘制后的画布状态清理 Foreground = 7, // 预留给粒子之上的一切前景/特效 }

每个层的注释都写明了职责：0 = 最底层，7 = 最前层，RenderManager.drawParticles按序迭代这些层。插件可以通过IContainerPlugin.layer声明自己所处层级，或者根据实现了哪些钩子方法（draw、clearDraw、drawSettingsSetup、drawSettingsCleanup等）被自动分配到对应层。这套设计把“背景、遮罩、插件内容、粒子、前景”的绘制顺序从隐式约定变成了显式管线，是 4.x 渲染架构的核心变化。

2.2 HDR 精度系统（HDR Precision System）

CHANGELOG 条目为added new hdr precision system，其前身可以追溯到 4.0.0-alpha.0（2026-01-07）的三条记录：

• added hdr feature full implementation, colors are now hdr ready
• added hdr option, with fallback if not supported by the screen
• improved hdr management, improved also big particles config

4.2.1 进一步记录为：hdr precision enhancement — floating-point RGB pipeline for display-p3 colors, reduced banding and compensated animation speed in HDR mode，即面向 display-p3 广色域的浮点 RGB 管线，用于减少色带并补偿 HDR 模式下的动画速度。

该能力在配置层面的入口是 engine/src/Options/Interfaces/IOptions.ts 中的选项：

/** * Enables or disables the HDR mode, if enabled the particles will be rendered in a higher color precision */ hdr: boolean;

即在根配置中设置hdr: true即可开启；当屏幕不支持时会按 CHANGELOG 所述进行回退（fallback）。

2.3 粒子修改器系统（Particle Modifier System）

CHANGELOG 条目为added new particle modifier system。对应实现是 engine/src/Core/Interfaces/IParticleModifier.ts 定义的接口：

export interface IParticleModifier { /** 是否启用该修改器 */ readonly enabled: boolean; /** 覆盖后的填充色 */ readonly fillColor?: IHsl; /** 唯一标识，用于后续移除 */ readonly id: string; /** 覆盖后的不透明度 */ readonly opacity?: number; /** 优先级：数值越大越晚应用（覆盖低优先级修改器） */ readonly priority: number; /** 覆盖后的半径 */ readonly radius?: number; /** 覆盖后的速度因子 */ readonly speedFactor?: number; /** 覆盖后的描边色 */ readonly strokeColor?: IHsl; }

这是一个“按 id 注册、按 priority 排序生效、可单独移除”的动态属性覆盖机制，允许在运行时对单个粒子的颜色、尺寸、透明度、速度做临时干预，而不需要改动全局配置。

2.4 Canvas 背景与自定义绘制回调

CHANGELOG 还有两条相邻记录：added support for canvas background and custom draw callbacks（fb71bd9）与紧随其后的improved support for canvas background and custom draw callbacks（a88798c）。结合 DrawLayer 枚举可知其落点：层 0（BackgroundElement，自动把background.element声明的 DOM 元素绘制进 canvas）与层 1（BackgroundDraw，执行用户提供的background.draw(ctx, delta)回调）。这意味着用户可以在引擎的绘制管线内部拿到 canvas 上下文，插入任意自绘内容，且绘制顺序由层号保证。

三、4.0 主线：颜色模型、调色板与空间数据结构重构

4.0.0 正式发布于 2026-05-15，但其核心工作集中在长达数月的 alpha/beta 周期中。CHANGELOG 中这几个条目值得单独展开。

3.1fill取代color与调色板（palette）支持

4.0.0-alpha.27（2026-03-09）记录了 5 条 feat：

• replaced particles.color with particles.fill to have (almost) same options as particles.stroke—— 粒子配色从单一的color字段重构为fill+stroke对称结构，两者拥有几乎相同的可配置项（含范围值、动画等）；
• update particle color handling to use fill and stroke properties—— 颜色处理全面切换到新字段；
• added palette support to engine、added fill palette support, more palettes too in config、added matrix shape with character animation and palette updates—— 引擎级调色板系统上线，仓库中palettes/目录下的 atmosphere、fireworks、nature、space 等 20 个调色板包即服务于该特性。

4.0.0-beta.7 又补充了两条：improved split color management and offset handling, and updateAnimation function（fix）与added palette support to particles options（feat）。4.0.0-beta.9 则修复了improved palette stroke width type。从这些连续条目可以推断，调色板特性在 4.0 周期内经历了 fill/stroke 类型收敛与拆分色（split color）处理的多次打磨后才定型。

3.2 QuadTree 替换为 SpatialHashGrid

4.0.0-alpha.25（2026-02-21）的一条 feat 具有架构意义：

**core:** replace QuadTree with SpatialHashGrid

当前源码中，engine/src/Core/Utils/SpatialHashGrid.ts 实现了这一替换：粒子按位置被插入cellSize尺寸网格对应的单元格（Map<string, Particle[]>），查询时只需遍历与查询范围（圆形/矩形）相交的少量单元格，并对 Circle/Rectangle 查询对象做了对象池（#circlePool/#rectanglePool）以减少每帧分配。相比四叉树，这种哈希网格在粒子密集且每帧全量重建的场景下开销更平稳。CHANGELOG 早期（1.17 系列）中improved performance of QTree fixing rectangle的条目，正好构成了“QuadTree 优化多年 → 最终被哈希网格整体替换”的演进闭环。

3.3 Zoom 插件化、效果粒子与卡片形状

• 4.0.0-alpha.23（2026-02-11）：added zoom feature (disabled by default)与moved zoom feature to plugin，即缩放能力先落地为默认关闭的特性，随即被移入独立插件包（对应仓库中的 plugins/zoom）。
• 4.0.0-alpha.9（2026-02-02）：add effect particles with configuration and drawing logic、add full card shape, and utilities for path drawing，配套修复包括“粒子无法写入 canvas 时回收入对象池”（add particle to pool when unable to add to the canvas）与“只实例化实际用到的 path 生成器以修复性能回退”。
• 4.0.0-beta.0 至 4.0.0-beta.17 期间为收敛期，代表性修复是 beta.17 的position.z value now is integer, so buckets will work better——z 坐标取整以改善深度分桶（DrawLayer 中Particles = 5层按 z 分桶渲染的前置条件）。

四、2.0/2.10.0：v2 大迁移——插件化是理解整个仓库结构的关键

CHANGELOG 中最庞大的条目是 2.10.0（2023-06-03，跨越 v2.0.0-alpha.0 的所有变更）。它确立了 tsParticles 延续至今的模块化架构，仓库中plugins/、shapes/、updaters/、interactions/、effects/、paths/各目录的独立包形态正是其产物。核心变更可归纳为四类：

4.1 能力全部外移为独立包（Breaking）

CHANGELOG 中的一组 breaking 条目：

• moved all updaters to external packages, breaking
• moved all interactions in external packages, breaking
• moved all shapes to external packages, breaking
• moved all plugins to external packages, breaking
• moved absorbers to an external plugin, breaking
• moved polygon mask to external plugin (breaking)
• moved out click interactions to external packages, breaking
• moved particles.js compatibility to another package
• moved hsv color management to external plugin since it's not commonly used

配套的性能决策：moved all easings to plugin packages, slim now depends on easing-quad since it's the default（缓动函数全部移入插件包，slim 包因 quad 是默认缓动而依赖它）；removed all canvas context save/restore calls；removed support for very old browsers that don't support requestAnimationFrame；splitting engine from slim and full bundles (v2)。

4.2 API 层的重要新能力

• 自定义随机源：added new tspRandom function and setRandom for customizing all the random behaviors，所有随机行为可替换；
• ResizeObserver：added resize observer, this will replace window.resize if available，在有 ResizeObserver 的环境中替代窗口 resize 事件；
• 动画 decay/delay：added decay to all animations、implemented delay options in opacity, size and colors updaters，为动画对象统一引入衰减速率与延迟（对应 2.3.0 的added decay options (not used yet) to animation objects先行铺垫）;
• 选项加载函数化：added new functions for loading options, this will be useful for removing all the classes，为后续“去类化”的配置加载做准备；
• 枚举改常量：**engine:** changed all enums to const, smaller output size，且明确标注BREAKING CHANGES: enums are not exported anymore, this could break javascript usages——这是 2.x 唯一的显式 breaking 标注，使用枚举导出的 JavaScript 代码会被影响（从源码看，engine/src/Enums 下的 OutMode、MoveDirection 等至今仍以 const 组织）。

4.3 插件体系首批落地（2.11.0，2023-07-12）

2.11.0 记录了三类内容：修复（calc position、getPositionOrSize、emitters 相关）与特性——added animated gif support to image drawer（GIF 动图粒子）、added refresh flag for loading plugins（防止实例被多次刷新）、added setLogger and getLogger functions, this will prevent console.log mistakenly left（日志接管）、added tree shaking（配合 engine/package.json 中的"sideEffects": false让打包器可安全摇树），以及导出插件的完整实现：

adding export plugins export plugins completed, image and json improved new export function, using blob as output for all functions

即容器画面可以导出为图片或 JSON，统一以 Blob 作为输出。

4.4 v2 早期的兼容性策略

2.10.1 之前还有两条重要的“降级风险对冲”记录：restored options compatibility with v1 and pjs, it's easier to migrate to v2 this way（v2 恢复对 v1/particles.js 旧选项的兼容以平滑迁移）与removing the id constraint, a random one will be generated（容器 id 不再必填，自动生成随机 id）。

五、3.x 线：动态导入、背景遮罩与动画循环控制

2.12.0 之后到 4.0 之前的 3.x 版本，CHANGELOG 记录了若干对使用者可见的特性：

• 3.2.0（2024-01-31）：added background mask image support（背景遮罩支持图片）、added new particle external interaction、added some dynamic imports, plugins will be loaded only if used（插件按需动态加载），此后 CHANGELOG 中出现大量improving dynamic imports条目，3.2.2 专门fixed circular deps detection and other issues with dynamic imports，3.3.0 则fixed issues in Chrome with async rAF function, reduced async methods for vite builds——可见动态导入优化在 Chrome/Vite 组合下反复打磨过；
• 3.4.0（2024-05-12）：changed bundles loading method, no more preloading plugins，bundle 不再预加载插件，与 bundles/ 下各包的按需加载策略一致；同时improved trail effect and tilt；
• 3.5.0（2024-07-01）：added customization for animation loop, fixes #5355，动画主循环行为可定制；
• 3.6.0（2024-11-18）：颜色语法扩展，first try of oklch color/fixed oklch color, added lch color too（修复 issue #5409），随后 3.7.0 又added new named color plugin, and hex color in the engine，并修复了 Firefox 下 canvas 每帧扩张的问题；
• 3.8.0（2025-01-23）：全屏模式样式系列修复（fixed style reparation and full screen toggle issues、improved style duplication），3.8.1 修复fullScreen激活时的 z-index 问题（issue #5458）；
• 3.9.0（2025-08-01）：fixed some issues in groups, some things are still not working——粒子 groups 问题修复的收尾（3.0.1 的fixed bug when using particles groups与 3.6.0-beta.0 的fixed issue with removing particles when group is active是同一主题的更早修复）。

3.0.0（2023-12-04）本身也值得关注：added clear flag, enabled by default, if disabled, the canvas won't be cleared与added fade to trail effect共同构成了轨迹效果的开关体系；3.0.0-beta.4 引入added curl noise path plugin（对应仓库 paths/curlNoise）并删除了独立的多行文本 shape（并入标准 text shape）；3.0.0-beta.5 增加added new emoji shape, better performance than text shape（对应 shapes/emoji）。

六、修复条目的阅读方法与近期典型修复

这份 CHANGELOG 的Bug Fixes条目带有明确的 issue 与 commit 引用（如fixes #5903 (3e128d2)），阅读时可将其作为“症状 → 提交”的索引。近期（4.3.x）三条值得记录的修复：

1. 双重透明度计算（4.3.3，issue #5903）：fixed double opacity calc。结合 4.3.0 引入的绘制层与 modifier 系统，透明度现在经过多层管线（modifier 覆盖、动画、组覆盖），此修复消除了某一层被重复计算的问题；
2. 引擎初始化的公共实例（4.3.3）：fixed common instance usage in engine initialization，与 engine/src/initEngine.ts 及 engine/src/index.ts 的初始化入口相关；
3. deepExtend 连续加固：4.3.0 的improved deepExtend+fixed some issues in deepExtend、4.3.2 的fixed some issues in deepExtend，以及更早 4.0.0-alpha.26 的security fix for deepExtend。deepExtend负责把用户传入的选项对象与默认值深度合并，是配置系统的地基，其连续三次版本内修复说明合并逻辑（尤其是数组/嵌套结构处理）是配置问题的常见来源。

更早的高价值修复还包括：2.12.0 中fixed memory leak in destroyed particles by updaters, the z array wasn't filtered（issue #5101）——更新器销毁粒子时 z 排序数组未过滤导致的内存泄漏；fixed frozen frames (more than 1 seconds), this will fix the issue with pause on blur——长帧冻结与失焦暂停的联动问题；solved performance drop issue after refresh（issues #2809/#2815/#2936）——refresh()后性能下降，与 2.11.0 引入的refresh flag特性互为表里。

七、升级路径建议与破坏性变更清单

基于 CHANGELOG 的完整脉络，跨大版本升级时需要重点核对的事项：

另外两条使用层面长期有效的约束（engine/README.md 的 Common pitfalls 章节）：插件要在tsParticles.load()之前加载，否则可能不生效；每个 shape/updater 需要其对应包先被加载。

八、结语

engine/CHANGELOG.md 不只是一份发版清单，它完整呈现了 tsParticles 引擎的三次架构跃迁：2.0 的插件化拆分（一切能力外移、sideEffects: false支持摇树）、3.x 的按需加载与颜色系统扩展（动态导入、oklch/lch、背景遮罩图片）、4.x 的渲染管线化（DrawLayer 八层管线、HDR 浮点精度、IParticleModifier 运行时覆盖）。结合 engine/src/Core 下的 Container、RenderManager、CanvasManager 等实现与 engine/src/Enums/DrawLayer.ts、engine/src/Core/Utils/SpatialHashGrid.ts 等关键文件，可以验证 CHANGELOG 中每一条feat都有对应的源码落点。在升级@tsparticles/engine时，建议按本文第七节的清单逐项核对，并将Note: Version bump only条目直接跳过。

【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles