NextJS导入Chakra-UI后触发TypeError报错求助

问题场景 #

仅在NextJS的_app.js中导入@chakra-ui/react的ChakraProvider组件（未在代码中使用），页面就触发Server Error，报错信息如下：

Server Error
TypeError: Cannot read properties of undefined (reading 'toLowerCase')

This error happened while generating the page. Any console logs will be displayed in the terminal window.
Call Stack
userAgentContains
file:///Users/dhineshbabumuthuraj/Documents/Dhineshbabu/learning/JavaScript/nextjs-apps/sample-nextjs-app1/node_modules/framer-motion/dist/es/projection/node/create-projection-node.mjs (1470:25)
<unknown>
file:///Users/dhineshbabumuthuraj/Documents/Dhineshbabu/learning/JavaScript/nextjs-apps/sample-nextjs-app1/node_modules/framer-motion/dist/es/projection/node/create-projection-node.mjs (1476:20)
ModuleJob.run
node:internal/modules/esm/module_job (218:25)
async ModuleLoader.import
node:internal/modules/esm/loader (329:24)
async importModuleDynamicallyWrapper
node:internal/vm/module (430:15)

当前_app.js代码：

import Layout from '../components/layout/layout';
import '../styles/globals.css';
import { ChakraProvider } from '@chakra-ui/react';

export default function App({ Component, pageProps }) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  );
}

解决方案 #

1. 正确使用ChakraProvider包裹根组件 #

ChakraProvider是Chakra-UI的核心根组件，必须用来包裹整个应用才能正常工作。仅导入但不使用会导致其依赖的framer-motion在服务端渲染时找不到所需的环境变量（比如userAgent），从而触发报错。修改后的_app.js代码：

import Layout from '../components/layout/layout';
import '../styles/globals.css';
import { ChakraProvider } from '@chakra-ui/react';

export default function App({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Layout>
        <Component {...pageProps} />
      </Layout>
    </ChakraProvider>
  );
}

2. 修复framer-motion版本兼容性问题 #

Chakra-UI对framer-motion的版本有严格要求，版本不匹配会引发服务端渲染异常。执行以下命令重新安装适配的版本：

# 卸载现有framer-motion
npm uninstall framer-motion
# 安装Chakra-UI推荐的稳定版本（以v6.5.1为例，可根据Chakra官方文档调整）
npm install framer-motion@^6.5.1

3. 临时禁用服务端渲染（调试用） #

如果只是临时调试，可以给ChakraProvider添加ssr={false}属性，强制组件在客户端渲染，避免服务端环境的限制：

<ChakraProvider ssr={false}>
  <Layout>
    <Component {...pageProps} />
  </Layout>
</ChakraProvider>

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