Next.js 14中Styled-Components的ThemeProvider主题palette访问问题

在Next.js 14中使用styled-components配置主题时，无法访问主题对象的palette属性，尝试多种调整均无效，具体情况如下：

错误现象 #

代码中无法访问theme.palette，报错提示该属性不存在。

相关代码 #

BodyComponent.tsx #

"use client";
// Vendors
import { PropsWithChildren, ReactElement } from "react";
import { ThemeProvider } from 'styled-components';
// styles
import AppTheme from "@/theme/ui.theme";

const BodyComponent = ({children, className}: PropsWithChildren<{className: string}>): ReactElement => {
  
  return (
    <body className={className}>
      <ThemeProvider theme={AppTheme}>
        { children }
      </ThemeProvider>
    </body>
  );
};

export default BodyComponent;

Theme.ts #

const mode_colors = {
  light: '255 255 255',
  dark: '0 0 0',
}

const status_colors = {
  colorSucessA: '#81c784',
  colorSucessB: '#66bb6a',
  colorSucessC: '#388e3c',
  colorWarningA: '#ffb74d',
  colorWarningB: '#ffa726',
  colorWarningC: '#f57c00',
  colorSeveralA: '#e57373',
  colorSeveralB: '#f44336',
  colorSeveralC: '#d32f2f',
};

const app_colors = {
  primaryColorA: '#FFC377',
  primaryColorB: '#FFAD45',
  primaryColorC: '#FF8E00',
  contrastColorA: '#d4dc85',
  contrastColorB: '#ccd75b',
  contrastColorC: '#2596be',
}

const AppTheme = {
  palette: {
    ...app_colors,
    ...status_colors,
    ...mode_colors,
  }
};

export default AppTheme;

样式组件文件 #

'use client';
// Vendors
import { css } from "styled-components";

const rootStyle = () => {
  return css`
    :root {
      --mode-background: rgb(${({theme}) => theme.palette.dark});
      --pattern-background: url(/patterns/graph-paper-dark.svg);
      --font-color: rgb(${({theme}) => theme.palette.light});
      
      @media (prefers-color-scheme: light) {
        --mode-background: rgb(${({theme}) => theme.palette.light});
        --pattern-background: url(/patterns/graph-paper-light.svg);
        --font-color: rgb(${({theme}) => theme.palette.dark});
      }
    }
  `;
};

已尝试的解决方法 #

• 修改主题对象，仅保留颜色属性
• 在ThemeProvider所在文件内直接声明主题
• 调整ThemeProvider的元素层级
• 尝试扩展styled-components的DefaultTheme类型：

// Vendors
import { DefaultTheme } from "styled-components";
// Constants
import colors from "./constants/colors.constants";

const AppTheme: DefaultTheme = {
  palette: colors,
};

export default AppTheme;

解决方法 #

1. 正确扩展DefaultTheme类型 #

styled-components的类型系统需要显式扩展DefaultTheme来识别自定义主题结构，仅给主题对象标注类型不够，需创建类型声明文件：

在项目根目录或src目录下创建styled.d.ts文件，内容如下：

import 'styled-components';
import { AppTheme } from './theme/ui.theme'; // 确保导出AppTheme的类型

declare module 'styled-components' {
  export interface DefaultTheme extends typeof AppTheme {}
}

如果不想导入类型，也可以直接在声明文件中定义主题结构：

import 'styled-components';

declare module 'styled-components' {
  export interface DefaultTheme {
    palette: {
      light: string;
      dark: string;
      colorSucessA: string;
      colorSucessB: string;
      colorSucessC: string;
      colorWarningA: string;
      colorWarningB: string;
      colorWarningC: string;
      colorSeveralA: string;
      colorSeveralB: string;
      colorSeveralC: string;
      primaryColorA: string;
      primaryColorB: string;
      primaryColorC: string;
      contrastColorA: string;
      contrastColorB: string;
      contrastColorC: string;
    };
  }
}

2. 检查样式组件的使用范围 #

确保rootStyle应用的组件处于ThemeProvider的包裹范围内，比如将其作为全局样式组件使用：

'use client';
import { createGlobalStyle } from 'styled-components';
import { rootStyle } from './你的样式文件路径';

const GlobalStyle = createGlobalStyle`
  ${rootStyle()}
`;

// 在App组件中引入
export default function App() {
  return (
    <BodyComponent>
      <GlobalStyle />
      {/* 其他页面内容 */}
    </BodyComponent>
  );
}

3. 适配Next.js 14的服务端渲染 #

Next.js 14的App Router模式下，需要开启styled-components的编译器支持，在next.config.js中配置：

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

module.exports = nextConfig;

如果使用Pages Router，需在babel.config.js中添加插件：

{
  "presets": ["next/babel"],
  "plugins": ["styled-components"]
}

4. 导出主题类型 #

在Theme.ts中导出主题的类型，方便类型声明文件引用：

// Theme.ts
export type AppThemeType = typeof AppTheme;

const AppTheme = {
  // ... 主题内容
};

export default AppTheme;

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