Particles.js 是一个轻量级的粒子特效库，它通过 canvas 绘制大量运动粒子，并支持连线、鼠标交互等效果。很多人在第一次使用时会把注意力全部放在粒子数量、颜色和速度等参数上，结果页面却只显示一个空白区域。其实这类问题大多是加载环节出错：脚本没有被正确引入、初始化时机太早导致 DOM 未就绪，或者容器高度为 0 导致 canvas 无法撑开。下面从加载顺序、容器设置、配置方式三个角度展开，并给出可直接运行的完整示例。
脚本加载顺序与初始化时机
Particles.js 依赖浏览器文档对象模型，它需要在目标容器已经存在于页面之后才能绑定。如果把初始化代码放在 <head> 中并且没有监听 DOMContentLoaded 事件，那么脚本执行时 document.getElementById('particles-js') 会返回 null，后续设置必然报错。常见的错误信息是 Cannot read property 'appendChild' of null 或者 particlesJS is not defined。
解决思路有两种。第一种是把初始化脚本放到页面底部，也就是紧挨着 </body> 之前，这样 DOM 已经解析完毕。第二种是在 <head> 中使用 DOMContentLoaded 事件包裹初始化代码。更推荐的方式是使用 defer 属性加载外部脚本，它会延迟到 DOM 解析完成后才执行。需要注意的是，如果使用 CDN 引入 Particles.js 库本身，也要保证库文件先于初始化脚本执行。比如下面的顺序是正确的：先引入库，再在页面底部调用 particlesJS 函数。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>Particles.js 加载示例</title>
<style>
#particles-js {
width: 100%;
height: 400px;
background-color: #0a0a0a;
}
</style>
</head>
<body>
<div id="particles-js"></div>
<!-- 先引入 Particles.js 库 -->
<script src="https://cdn.jsdelivr.net/npm/particles.js@2.0.0/particles.min.js"></script>
<!-- 再在底部执行初始化 -->
<script>
particlesJS('particles-js', {
particles: {
number: { value: 80, density: { enable: true, value_area: 800 } },
color: { value: '#ffffff' },
shape: { type: 'circle' },
opacity: { value: 0.5, random: false },
size: { value: 3, random: true },
line_linked: {
enable: true,
distance: 150,
color: '#ffffff',
opacity: 0.4,
width: 1
},
move: {
enable: true,
speed: 6,
direction: 'none',
random: false,
straight: false,
out_mode: 'out',
bounce: false
}
},
interactivity: {
detect_on: 'canvas',
events: {
onhover: { enable: true, mode: 'repulse' },
onclick: { enable: true, mode: 'push' },
resize: true
},
modes: {
grab: { distance: 400, line_linked: { opacity: 1 } },
bubble: { distance: 400, size: 40, duration: 2, opacity: 8, speed: 3 },
repulse: { distance: 200, duration: 0.4 },
push: { particles_nb: 4 },
remove: { particles_nb: 2 }
}
},
retina_detect: true
});
</script>
</body>
</html>
容器高度与canvas尺寸问题
Particles.js 创建 canvas 时会读取容器元素的宽高，并把这个尺寸作为画布的实际渲染尺寸。如果容器没有设置 height，或者父级元素高度为 0，那么 canvas 会以 0 高度创建，粒子自然完全不可见。很多开发者误以为给容器设置 width: 100% 就够了，实际上在标准文档流中，块级元素的宽度默认可自动填充，但高度必须由内容或显式样式决定。一个空的 <div> 如果没有内容也没有 height 声明，其高度就是 0。
解决方法是在 CSS 中给容器一个明确高度，例如 height: 400px 或 height: 100vh。如果希望粒子背景铺满整个视口，可以使用 position: fixed 加上 top: 0; left: 0; width: 100%; height: 100%，并把其他内容放在更高层级的 z-index 上。另外，如果页面在移动端或者存在动态布局变化，建议监听 resize 事件，Particles.js 会重新计算 canvas 尺寸，但前提是容器本身的尺寸变化能够被浏览器正确报告。配置对象中的 resize: true 就是为此准备的。
还有一个细节：当容器使用百分比高度时，必须保证其父元素具有确定的高度。比如 body 和 html 默认高度由内容决定，如果直接给容器设置 height: 100%，实际计算可能仍为 0。这时需要给 html, body 设置 height: 100%，或者直接使用 100vh 单位规避这一问题。
配置方式与常见排错
Particles.js 支持两种配置传递方式：直接在 particlesJS 函数中传入 JavaScript 对象，或者通过 particlesJS.load 方法异步加载一个 JSON 配置文件。第一种方式适合配置量不大、希望所有参数都写在同一个 HTML 文件里的场景。第二种方式适合配置复杂、需要团队协作或者从后端动态生成配置的场景。两种方式效果完全一样，但加载 JSON 时要注意跨域问题：如果 JSON 文件放在其他域名下且没有正确的 CORS 头，浏览器会阻止加载，导致粒子无法初始化。
使用 JSON 配置的典型写法如下：
// 页面底部脚本
particlesJS.load('particles-js', 'assets/particles-config.json', function() {
console.log('粒子动画加载完成');
});
上面代码中的第二个参数是配置文件路径。如果控制台出现 Failed to fetch 或者 404 Not Found，首先要检查路径是否正确。对于本地文件直接双击打开 HTML 的情况，浏览器会以 file:// 协议加载，此时 fetch 本地 JSON 会被浏览器安全策略阻止，所以尽量使用本地服务器环境测试，比如 VS Code 的 Live Server 插件或 npx http-server。
另一个容易被忽略的问题是配置对象中的键名错误。Particles.js 对配置对象的字段名称非常敏感，例如粒子数量字段是 number.value 而不是 amount，连线配置是 line_linked 而不是 lineLinked。如果少写或者写错一个下划线，整个动画可能不会报错但也不显示粒子。建议从官方默认配置开始修改，确认动画正常后再逐项调整参数。
性能优化与初始化清理
粒子数量、连线距离和移动速度会直接影响页面性能。在配置中，number.value 控制粒子总数，line_linked.distance 控制多少像素内进行连线，move.speed 控制运动速度。如果粒子数量超过 150 并且开启连线，在低端移动设备上帧率会明显下降。可以通过减小粒子数量、关闭连线或降低 line_linked.opacity 来优化。另外，density.enable 可以根据屏幕区域自动调整粒子密度，建议保持开启。
如果页面是单页应用，在组件卸载或路由切换时需要手动销毁 Particles.js 实例。Particles.js 本身没有提供官方 destroy 方法，但可以通过移除容器内生成的 canvas 元素来实现清理。例如：
// 在组件卸载或页面跳转前调用
var container = document.getElementById('particles-js');
if (container) {
while (container.firstChild) {
container.removeChild(container.firstChild);
}
}
清理之后重新初始化时，直接再次调用 particlesJS 即可。注意不要重复初始化同一个容器，否则会出现多个 canvas 堆叠，导致视觉重叠和额外的内存消耗。一个常见的做法是维护一个初始化标记，或者每次初始化前先执行上述清理操作。
Particles.js粒子动画网页加载修改时间：2026-08-20 17:18:45