Next.js：解决 window is not defined 错误

2025-02-12 14:31:54

在使用 Next.js 开发项目时，你可能会遇到 window is not defined 这个错误，尤其是在使用服务器端渲染（SSR）时。因为 window 是浏览器环境中的一个全局对象，而在服务器端渲染的过程中并不存在 window 对象，所以如果你尝试在服务端访问 window，就会抛出这个错误。

在本文中，我们将探讨这个问题的根源，并给出几种常见的解决方法，以便在开发 Next.js 应用时避免或修复这种错误。

一、`window is not defined` 错误的根本原因

window is not defined 错误通常出现在尝试在 服务器端渲染（SSR）期间访问浏览器特有的 API（如 window）时。由于 SSR 会在 Node.js 环境中运行，Node.js 本身并没有 window 这个全局对象，因此会导致这种错误。

例如，在组件中直接访问 window.location 或在生命周期钩子中使用 window 对象时，通常会在服务器端渲染时触发错误：

if (window) {
  console.log(window.location.href); // 这个会在服务器端抛出错误
}

二、解决方法

1. 使用 `typeof window !== 'undefined'` 进行判断

最常见的解决方案是在访问 window 对象之前，先进行判断，确保代码只在客户端执行，而不是在服务器端执行。具体做法是检查 window 是否存在。可以通过以下方式进行条件判断：

if (typeof window !== 'undefined') {
  // 只有在客户端环境下才会执行这段代码
  console.log(window.location.href);
}

这样，在服务器端渲染期间，typeof window 会返回 'undefined'，因此代码不会执行，从而避免了错误。

2. 使用 `useEffect` 钩子（仅在客户端执行）

如果你在 React 组件中使用了 window 对象，建议将相关代码放到 useEffect 中，因为 useEffect 只有在组件挂载到客户端之后才会被调用。在此之前，组件的服务器端渲染是不会执行 useEffect 中的代码的。这样可以确保你只在客户端执行需要访问 window 对象的代码。

import { useEffect } from 'react';

const MyComponent = () => {
  useEffect(() => {
    // 只有在客户端环境下才会执行这段代码
    console.log(window.location.href);
  }, []);

  return <div>My Component</div>;
};

3. 使用 `next/dynamic` 动态加载

如果你有些组件只需要在客户端渲染，可以使用 动态加载，在客户端时再加载这些组件。next/dynamic 可以让你指定一个组件只在客户端加载，从而避免服务器端渲染期间访问 window。

import dynamic from 'next/dynamic';

const MyClientOnlyComponent = dynamic(() => import('./MyClientOnlyComponent'), {
  ssr: false, // 禁用服务端渲染
});

const MyPage = () => {
  return (
    <div>
      <MyClientOnlyComponent />
    </div>
  );
};

export default MyPage;

通过设置 ssr: false，MyClientOnlyComponent 组件将只在客户端渲染，避免了 window is not defined 错误。

4. 使用 `next/head` 进行浏览器特定的代码处理

在某些情况下，你可能需要在页面加载时插入一些特定于浏览器的代码。Next.js 提供了一个 next/head 模块来帮助在页面的 <head> 部分插入代码，例如引入特定的脚本或样式。在这种情况下，你可以将浏览器相关的脚本放在 useEffect 钩子中，确保它们只在客户端加载。

import Head from 'next/head';

const MyPage = () => {
  return (
    <div>
      <Head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              if (typeof window !== 'undefined') {
                console.log(window.location.href);
              }
            `,
          }}
        />
      </Head>
      <h1>My Page</h1>
    </div>
  );
};

export default MyPage;