在 Node Video 中实现粒子特效之前，有一个重要前提需要明确：该功能仅支持 v3.8.0 及以上版本。你需要通过 ParticleCanvas 创建画布，加载使用 GLSL 300 es 编写的着色器（片元着色器中必须包含 precision 声明），然后将 Float32Array 格式的位置数据按指定顺序传入，再依次调用 setParticles（注意 count 参数须为整数）和 start() 才能正常启动渲染。
这套机制底层直接调用 Node Video 内置的 WebGL 渲染管线以及自定义着色器能力，本质上是完全依赖 GPU 进行粒子运算，而非像过去那样借助第三方 JS 库。这种方案的优势在于性能稳定、帧率更高，但代价是需要你亲自编写着色器代码。
确认 Node Video 版本支持粒子系统
首先打开终端，执行 node-video --version，检查屏幕上显示的版本号是否为 v3.8.0 或更高。如果版本低于此，系统中将缺少 particle-renderer 模块，强行调用会导致 WebGL 初始化失败，且不会出现任何错误提示——直接黑屏无响应。因此这一步绝对不可跳过。
若版本过低，使用 npm install -g node-video@latest 升级，然后重启终端并再次验证。这一操作花费不到半分钟，却能避免后续大量排查时间。
创建基础粒子画布
新建一个 particles.js 文件，写入以下代码：
const { ParticleCanvas } = require('node-video');
const canvas = new ParticleCanvas({ width: 1920, height: 1080, fps: 60 });
注意一个常见的陷阱：在 require('node-video') 之后 必须立即执行 这段代码。因为 ParticleCanvas 实例会绑定全局 WebGL 上下文，如果延迟创建，上下文可能已被其他模块占用，导致后续粒子节点注册失败。根据经验，很多人正是卡在这一步。
加载 GPU 粒子着色器
Node Video 的粒子系统只支持 GLSL 300 es 编写的着色器，不接受任何 JavaScript 模拟逻辑。因此你需要准备两个文件：
shader.vert—— 顶点着色器shader.frag—— 片元着色器
将这两个文件放入项目新建的 shaders/ 目录下，然后调用：
canvas.loadShader('shaders/shader.vert', 'shaders/shader.frag');
这里有一个极易被忽略的细节：片元着色器文件末尾必须包含 precision highp float; 声明。如果缺失该行，在 iOS 设备上所有粒子将渲染为纯黑色，且控制台不会显示任何警告，排查起来会非常棘手。
注入粒子数据并启动
整个流程分为三个步骤，必须严格按顺序执行，中间不能插入任何异步操作（例如 setTimeout、fetch），否则粒子坐标缓冲区尚未就绪，画面会卡死在第一帧。
第一步：生成粒子位置数组。格式使用 Float32Array，每三个数值代表一个粒子的 xyz 坐标。
第二步：调用 canvas.setParticles(positions, count)。注意 count 必须是整数，切勿写成 positions.length / 3 这种可能产生浮点的结果——传入小数会触发静默崩溃，进程直接退出且不留任何日志。
第三步：执行 canvas.start()，启动渲染循环。之后粒子便会在 GPU 上持续运行。
