在Next.js中使用react-mathquill遇window未定义错误的解决办法

问题描述 #

在Next.js项目中使用react-mathquill时，刷新页面触发ReferenceError: window is not defined错误，错误栈指向@edtr-io/mathquill模块的服务端执行代码。已尝试以下操作但未解决：

• 用next/dynamic禁用SSR动态导入组件
• 动态导入使用react-mathquill的自定义组件
• 升级Next.js到v15.0.4（升级后路由跳转至目标页面也会报错）

包版本信息：

"next": "13.5.6",
"react": "^18.2.0",
"react-mathquill": "^1.0.3",

可行解决方案 #

1. 完整动态导入react-mathquill并禁用SSR #

直接动态导入整个react-mathquill模块，确保仅在客户端渲染：

import dynamic from 'next/dynamic';

// 动态导入整个模块，禁用SSR
const MathQuill = dynamic(
  () => import('react-mathquill'),
  { 
    ssr: false,
    loading: () => <div>加载数学编辑器...</div> // 可选加载占位组件
  }
);

// 使用组件
export default function MathEditor() {
  return (
    <div>
      <MathQuill.EditableMathField latex="\frac{d}{dx}x^2 = 2x" />
      <MathQuill.StaticMathField latex="\sum_{i=1}^n i = \frac{n(n+1)}{2}" />
    </div>
  );
}

2. 客户端环境判断后延迟导入组件 #

通过useEffect在客户端环境下异步加载组件，避免服务端执行时访问window：

import { useState, useEffect } from 'react';

export default function MathEditor() {
  const [EditableMathField, setEditableMathField] = useState(null);
  const [StaticMathField, setStaticMathField] = useState(null);

  useEffect(() => {
    // 仅在客户端环境加载模块
    if (typeof window !== 'undefined') {
      import('react-mathquill').then(({ EditableMathField, StaticMathField }) => {
        setEditableMathField(EditableMathField);
        setStaticMathField(StaticMathField);
      });
    }
  }, []);

  // 未加载完成时显示占位
  if (!EditableMathField || !StaticMathField) {
    return <div>加载中...</div>;
  }

  return (
    <div>
      <EditableMathField latex="x^2 + y^2 = z^2" />
      <StaticMathField latex="e^{i\pi} + 1 = 0" />
    </div>
  );
}

3. 修改Next.js Webpack配置排除服务端编译 #

在next.config.js中配置webpack，让服务端编译时忽略react-mathquill及其依赖，避免服务端执行相关代码：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    // 服务端编译时排除相关模块
    if (isServer) {
      config.externals.push('react-mathquill', '@edtr-io/mathquill');
    }
    return config;
  },
};

module.exports = nextConfig;

配置完成后，结合方案1或方案2的动态导入方式使用组件。

4. 临时回退Next.js版本 #

如果升级到Next.js v15后问题恶化，可暂时回退到13.5.x的稳定版本，再配合上述客户端渲染方案使用。

额外注意事项 #

react-mathquill依赖mathquill的CSS样式，需确保在客户端加载：

import { useEffect } from 'react';

export default function MathEditor() {
  useEffect(() => {
    // 动态引入mathquill样式
    const styleLink = document.createElement('link');
    styleLink.rel = 'stylesheet';
    styleLink.href = 'https://cdnjs.cloudflare.com/ajax/libs/mathquill/0.10.1/mathquill.min.css';
    document.head.appendChild(styleLink);

    // 组件卸载时移除样式
    return () => document.head.removeChild(styleLink);
  }, []);

  // ... 组件其余代码
}

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