Next.js中使用styled-components报useDebugValue读取null属性错误求助

可能原因 #

• 版本不兼容：styled-components 与 React/Next.js 版本不匹配，比如新版 styled-components 依赖 React 18+ 特性，但项目 React 版本过低；或反之。
• App Router 配置缺失：使用 Next.js 13+ App Router 时，styled-components 需要特殊配置才能在客户端组件正常工作，未配置会导致 React 上下文异常。
• 重复 React 实例：项目存在多个 React 副本（如子依赖单独安装 React），导致 Hooks 无法关联正确上下文。
• 缓存残留：Next.js 构建缓存或开发服务器缓存未清理，旧依赖代码残留引发异常。

解决步骤 #

1. 统一依赖版本 #

先确认 styled-components 官方要求的 React/Next.js 兼容版本（查看其 package.json 的 peerDependencies），再执行以下命令重装兼容版本：

# 卸载现有包
yarn remove styled-components react react-dom next
# 安装指定兼容版本（示例：Next.js 13 + React 18 + styled-components 6.x）
yarn add next@^13 react@^18 react-dom@^18 styled-components@^6

2. 适配 Next.js App Router #

若使用 App Router：

• 在所有使用 styled-components 的组件顶部添加 'use client' 指令，强制客户端渲染：

'use client';
import styled from 'styled-components';

const StyledDiv = styled.div`
  padding: 20px;
  background-color: #eee;
`;

export default function MyComponent() {
  return <StyledDiv>测试内容</StyledDiv>;
}

• 修改 next.config.js 启用 styled-components 编译器：

/** @type {import('next').NextConfig} */
const nextConfig = {
  compiler: {
    styledComponents: true,
  },
};

module.exports = nextConfig;

3. 消除重复 React 实例 #

执行命令检查项目中 React 版本：

yarn list react

若输出多个版本，在 package.json 中添加强制统一配置：

// Yarn 1.x 使用 resolutions
"resolutions": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

// Yarn 2+ / npm 8+ 使用 overrides
"overrides": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

之后重新安装依赖：

yarn install

4. 彻底清理缓存 #

除删除 node_modules，还要清理 Next.js 缓存：

rm -rf node_modules .next
yarn cache clean
yarn install

重启开发服务器：

yarn dev

5. 检查自定义 Babel 配置 #

若项目有自定义 .babelrc 或 babel.config.js，需添加 styled-components 插件：

{
  "plugins": ["babel-plugin-styled-components"]
}

安装该开发依赖：

yarn add -D babel-plugin-styled-components

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