Next.js集成qr-code-styling报错：self is not defined

核心原因 #

qr-code-styling库依赖浏览器环境的self对象，而Next.js默认的SSR（服务器端渲染）会在服务器端执行组件代码，服务器环境中不存在self。即使使用useEffect包裹实例化逻辑，库本身的导入过程可能已经在服务器端触发了对self的访问，导致500错误。

有效解决方案 #

1. 使用Next.js动态导入禁用SSR #

通过Next.js的dynamic函数导入qr-code-styling，并指定ssr: false，强制该库仅在客户端加载执行：

import dynamic from 'next/dynamic';
import { useEffect } from 'react';

// 动态导入qr-code-styling，禁用服务器端渲染
const QRCodeStyling = dynamic(() => import('qr-code-styling'), {
  ssr: false,
  loading: () => <div>加载二维码中...</div> // 可选：加载状态提示
});

export default function ShareQRModal({ recipeUrl, isOpen }) {
  if (!isOpen) return null;

  useEffect(() => {
    if (!QRCodeStyling || !recipeUrl) return;

    // 实例化二维码
    const qrCode = new QRCodeStyling({
      width: 250,
      height: 250,
      data: recipeUrl,
      dotsOptions: {
        color: '#4299e1',
        type: 'rounded'
      },
      backgroundOptions: {
        color: '#ffffff'
      }
    });

    // 渲染到容器
    const container = document.getElementById('qr-code-container');
    if (container) {
      qrCode.append(container);
    }

    // 清理函数：避免重复渲染
    return () => {
      if (container) {
        container.innerHTML = '';
      }
    };
  }, [recipeUrl, QRCodeStyling]);

  return (
    <div className="modal-overlay">
      <div className="modal-content">
        <h3>分享食谱</h3>
        <div id="qr-code-container"></div>
        <button onClick={() => /* 关闭弹窗逻辑 */}>关闭</button>
      </div>
    </div>
  );
}

2. 额外检查：确保所有相关代码仅在客户端执行 #

如果还有其他地方调用了qr-code-styling的API，需包裹在浏览器环境判断中：

if (typeof window !== 'undefined') {
  // 这里写仅客户端执行的二维码相关逻辑
}

关键说明 #

• 仅用useEffect包裹实例化逻辑不足以解决问题，因为库的导入阶段可能已经在服务器端执行，触发了对self的访问。
• dynamic导入加ssr: false是Next.js处理客户端依赖库的标准方案，确保库的代码完全在浏览器环境中运行。

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