create-next-app 引入第三方React包时频繁出现Invalid hook call错误的问题咨询

Hey, I’ve run into this exact issue a few times when moving projects to Next.js, so let’s walk through what’s going on and how to fix it.

Why This Happens #

Your error stems from key differences between Create React App (CSR-only) and Next.js (SSR/SSG enabled), plus a few common dependency pitfalls:

• SSR vs. Browser Environment Mismatch: Many third-party packages (like react-burger-menu) rely on browser-only APIs (e.g., window, document) or run hooks during initialization. When Next.js renders these components on the server, those APIs don’t exist, and hook execution breaks the rules.
• Duplicate React Copies: Next.js ships with its own React dependency. If your package.json specifies a conflicting React version, or if node_modules ends up with multiple copies of React, hooks will throw errors because they can’t access the correct React context.
• Version Mismatches: Mismatched versions of react and react-dom (or Next.js’s internal React version) can also trigger this hook error.

Step-by-Step Solutions #

1. Fix Duplicate/Conflicting React Dependencies #

First, verify you don’t have multiple React copies or version mismatches:

• Run this command to check installed versions:

  npm list react react-dom
  

  Look for duplicate entries or versions that don’t match Next.js’s required React version (check Next.js docs for your Next.js version’s compatible React range).
• If duplicates exist, clean up your dependencies:
  1. Delete node_modules and package-lock.json (or yarn.lock if using Yarn)
  2. Run npm install (or yarn install) to reinstall dependencies
  3. If duplicates persist, run npm dedupe to flatten the dependency tree

2. Render Third-Party Components Client-Side Only #

Most UI packages that rely on browser APIs need to be rendered only on the client. Use Next.js’s dynamic import with ssr: false to disable server-side rendering for these components:

import dynamic from 'next/dynamic';

// Dynamically import the slide menu, disabling SSR
const Menu = dynamic(() => import('react-burger-menu').then(mod => mod.slide), {
  ssr: false,
  // Optional: Add a loading component while it loads
  loading: () => <div>Loading menu...</div>
});

export default function Home() {
  const styles = { /* your styles here */ };
  
  return (
    <Menu styles={styles}>
      <a id="home" className="menu-item" href="/">Home</a>
      <a id="about" className="menu-item" href="/about">About</a>
      <a id="contact" className="menu-item" href="/contact">Contact</a>
      <a className="menu-item--small" href="">Settings</a>
    </Menu>
  );
}

This ensures the component and its hooks only run in the browser, avoiding server-side hook errors.

3. Check Package SSR Compatibility #

Some packages have official Next.js/SSR support. Check the react-burger-menu docs or GitHub issues for specific guidance—you might find a recommended setup that doesn’t require disabling SSR entirely. For example, some packages let you initialize browser-dependent code in useEffect (which only runs client-side):

import { slide as Menu } from 'react-burger-menu';
import { useEffect, useState } from 'react';

export default function Home() {
  const [isClient, setIsClient] = useState(false);
  
  useEffect(() => {
    setIsClient(true);
  }, []);
  
  // Only render the menu on the client
  if (!isClient) return null;
  
  const styles = { /* your styles here */ };
  
  return (
    <Menu styles={styles}>
      {/* menu items */}
    </Menu>
  );
}

4. Verify Hook Rules (Quick Check) #

While less likely here (since it worked in CRA), double-check that you’re not breaking Hook rules in your Next.js components. Ensure hooks are called:

• At the top level of function components
• Not inside loops, conditions, or nested functions

Final Notes #

The most common fix for this scenario is using dynamic with ssr: false—it solves the browser API mismatch that’s almost certainly causing your error with react-burger-menu and other packages. Start with that, then clean up dependencies if the issue persists.

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