Next.js 14.1.0使用jQuery刷新页面报错：Cannot read properties of undefined (reading 'document')

问题原因 #

虽然组件加了"use client"指令，但Next.js的服务器端渲染（SSR）流程中，模块导入阶段仍会在服务器环境执行。jQuery源码初始化时会直接访问浏览器的document对象，而服务器端没有这个对象，导致刷新页面时触发TypeError: Cannot read properties of undefined (reading 'document')错误。路由跳转时是客户端导航，不会触发SSR，所以功能正常。

解决方案 #

方案1：在useEffect中动态导入jQuery #

useEffect仅在客户端执行，在这里动态导入jQuery能确保代码只在浏览器环境运行：

"use client";

import { useEffect } from "react";

export default function MyComponent() {
  useEffect(() => {
    // 动态导入jQuery，确保只在客户端加载
    import("jquery").then(($) => {
      const myClass = $(".myClass");
      console.log(myClass.prop("offsetHeight"));
    });
  }, []);

  return <div className="myClass"></div>;
}

方案2：用Next.js动态导入禁用SSR #

把jQuery相关逻辑抽成单独组件，通过next/dynamic导入并禁用SSR：

// JqueryComponent.tsx
"use client";

import { useEffect } from "react";
import $ from "jquery";

export default function JqueryComponent() {
  useEffect(() => {
    const myClass = $(".myClass");
    console.log(myClass.prop("offsetHeight"));
  }, []);

  return <div className="myClass"></div>;
}

然后在页面中导入：

import dynamic from "next/dynamic";

// 禁用SSR，确保组件只在客户端渲染
const JqueryComponent = dynamic(() => import("./JqueryComponent"), {
  ssr: false,
});

export default function Page() {
  return <JqueryComponent />;
}

方案3：全局CDN引入jQuery #

在根布局的body末尾引入jQuery CDN，避免模块导入在服务器端执行：

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        {children}
        {/* 在body末尾引入，确保DOM加载完成后再加载jQuery */}
        <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
      </body>
    </html>
  );
}

然后在组件中声明全局$变量：

"use client";

import { useEffect } from "react";

// 声明全局jQuery变量
declare var $: any;

export default function MyComponent() {
  useEffect(() => {
    const myClass = $(".myClass");
    console.log(myClass.prop("offsetHeight"));
  }, []);

  return <div className="myClass"></div>;
}

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