NextJS中react-tsparticles粒子不显示及CSS失效问题求助

问题概述 #

通过yarn add react-tsparticles为NextJS应用添加粒子背景时，页面仅渲染出canvas元素但粒子不显示，同时存在全局CSS无法生效的问题。相关代码如下：

粒子配置文件（particle-config.js） #

const ParticlesConfig = {
  autoplay: true,
  fullScreen: {
    enable: true,
    zIndex: 1,
  },
  particles: {
    number: {
      value: 10,
      density: {
        enable: false,
        value_area: 800,
      },
    },
    color: {
      value: '#fff',
    },
    shape: {
      type: 'star',
      options: {
        sides: 5,
      },
    },
    opacity: {
      value: 0.8,
      random: false,
      anim: {
        enable: false,
        speed: 1,
        opacity_min: 0.1,
        sync: false,
      },
    },
    size: {
      value: 4,
      random: false,
      anim: {
        enable: false,
        speed: 40,
        size_min: 0.1,
        sync: false,
      },
    },
    rotate: {
      value: 0,
      random: true,
      direction: 'clockwise',
      animation: {
        enable: true,
        speed: 5,
        sync: false,
      },
    },
    line_linked: {
      enable: true,
      distance: 600,
      color: '#ffffff',
      opacity: 0.4,
      width: 2,
    },
    move: {
      enable: true,
      speed: 2,
      direction: 'none',
      random: false,
      straight: false,
      out_mode: 'out',
      attract: {
        enable: false,
        rotateX: 600,
        rotateY: 1200,
      },
    },
  },
  interactivity: {
    events: {
      onhover: {
        enable: true,
        mode: ['grab'],
      },
      onclick: {
        enable: false,
        mode: 'bubble',
      },
      resize: true,
    },
    modes: {
      grab: {
        distance: 400,
        line_linked: {
          opacity: 1,
        },
      },
      bubble: {
        distance: 400,
        size: 40,
        duration: 2,
        opacity: 8,
        speed: 3,
      },
      repulse: {
        distance: 200,
      },
      push: {
        particles_nb: 4,
      },
      remove: {
        particles_nb: 2,
      },
    },
  },
  retina_detect: true,
  background: {
    color: '#111',
    image: '',
    position: '50% 50%',
    repeat: 'no-repeat',
    size: 'cover',
  },
};

export default ParticlesConfig;

首页文件（pages/index.js） #

import Head from 'next/head';
import Image from 'next/image';
import styles from '../styles/Home.module.css';
import ParticleBackground from '../components/ParticleBackground';

export default function Home() {
  return (
    <div className='home-main'>
      Aanvikshiki
      <ParticleBackground />
    </div>
  );
}

粒子背景组件（components/ParticleBackground.js） #

import React from 'react';
import Particles from 'react-tsparticles';
import ParticlesConfig from '../config/particle-config';
import styles from '../styles/Home.module.css';

const ParticleBackground = () => {
  return (
    <div id='particle-background'>
      <Particles
        id='tsparticles'
        particlesLoaded='particlesLoaded'
        particlesInit='particlesInit'
        options={ParticlesConfig}
        height='100vh'
        width='100vw'
      ></Particles>
    </div>
  );
};

export default ParticleBackground;

粒子不显示问题解决 #

1. 修复particlesInit和particlesLoaded属性 #

你当前传递的是字符串值，这两个属性需要接收函数而非字符串。若无需自定义初始化逻辑，可直接移除这两个属性：

// 修改后的ParticleBackground组件
const ParticleBackground = () => {
  return (
    <div id='particle-background'>
      <Particles
        id='tsparticles'
        options={ParticlesConfig}
      ></Particles>
    </div>
  );
};

2. 适配NextJS的SSR渲染 #

react-tsparticles依赖浏览器环境的Canvas API，在NextJS服务端渲染时会出现兼容性问题，需用动态导入并禁用SSR：

// 修改ParticleBackground组件的导入方式
import dynamic from 'next/dynamic';

const Particles = dynamic(() => import('react-tsparticles'), {
  ssr: false,
  loading: () => null,
});

const ParticleBackground = () => {
  return (
    <div id='particle-background'>
      <Particles
        id='tsparticles'
        options={ParticlesConfig}
      ></Particles>
    </div>
  );
};

3. 移除冗余的宽高属性 #

配置中fullScreen.enable已设为true，此时无需手动添加height='100vh'和width='100vw'，二者会导致布局层级冲突，直接移除即可。

全局CSS不生效问题解决 #

1. 全局CSS的正确引入方式 #

NextJS要求全局CSS必须在pages/_app.js中统一导入，不能在组件或页面中单独引入：

// pages/_app.js
import '../styles/globals.css'; // 替换为你的全局CSS文件路径

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

2. 检查类名引用逻辑 #

• 如果home-main是全局CSS中的类名，确保全局CSS文件中正确定义该类：

/* styles/globals.css */
.home-main {
  position: relative;
  z-index: 2; /* 确保内容层级高于粒子背景 */
  /* 其他样式规则 */
}

• 如果使用CSS Modules，需通过styles对象引用类名：

// 修改pages/index.js中的类名引用
<div className={styles['home-main']}>
  Aanvikshiki
  <ParticleBackground />
</div>

3. 调整粒子背景层级 #

为避免粒子背景覆盖页面内容，可在CSS中设置粒子容器的层级：

/* 全局CSS或模块CSS中添加 */
#particle-background {
  position: fixed;
  top: 0;
  left: 0;
  z-index: 0; /* 低于内容层级 */
}

内容的提问来源于stack exchange，提问作者elliot