如何在Next.js中使用styled-components的GlobalStyles全局样式？

前置操作：安装依赖 #

首先安装 styled-components 核心包，TypeScript 项目可同步安装类型声明包：

• 基础安装：npm install styled-components
• TypeScript 补充安装：npm install @types/styled-components -D

配置 Next.js 编译器支持 #

首先在项目根目录的 next.config.js 中开启 styled-components 编译支持，避免样式丢失、hydration 报错问题：

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

module.exports = nextConfig

分路由场景实现全局样式 #

场景1：Pages Router（Next.js 12及更早版本、13+保留pages目录的项目） #

1. 新建全局样式文件，例如 styles/GlobalStyle.js：

import { createGlobalStyle } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  * {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
  }

  body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    background-color: ${props => props.theme.colors.background || '#fff'};
    color: ${props => props.theme.colors.text || '#333'};
  }

  a {
    color: inherit;
    text-decoration: none;
  }
`;

export default GlobalStyle;

2. 在 pages/_app.js 中引入并渲染全局样式组件，配合主题可以同步引入 ThemeProvider：

import GlobalStyle from '../styles/GlobalStyle';
import { ThemeProvider } from 'styled-components';

const theme = {
  colors: {
    background: '#f5f5f5',
    text: '#222',
  }
}

export default function App({ Component, pageProps }) {
  return (
    <>
      <ThemeProvider theme={theme}>
        <GlobalStyle />
        <Component {...pageProps} />
      </ThemeProvider>
    </>
  )
}

场景2：App Router（Next.js 13+ 官方推荐的app目录模式） #

1. 新建客户端 Provider 组件（App Router 默认组件为服务端组件，styled-components 运行需要标记客户端），例如 app/StyledComponentsProvider.js：

'use client';

import { createGlobalStyle, ThemeProvider } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  * {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
  }

  body {
    font-family: system-ui, sans-serif;
    background-color: #fafafa;
    color: #1a1a1a;
  }
`;

const theme = {
  colors: {
    primary: '#0070f3',
  }
};

export default function StyledComponentsProvider({ children }) {
  return (
    <ThemeProvider theme={theme}>
      <GlobalStyle />
      {children}
    </ThemeProvider>
  );
}

2. 在根布局文件 app/layout.js 中引入 Provider 包裹全局内容：

import StyledComponentsProvider from './StyledComponentsProvider';

export const metadata = {
  title: 'My Next.js App',
  description: 'Next.js 项目',
}

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        <StyledComponentsProvider>
          {children}
        </StyledComponentsProvider>
      </body>
    </html>
  )
}

注意事项 #

• 必须开启 Next.js 内置的 styled-components 编译支持，不需要手动配置 babel 插件，否则会出现样式不生效、 hydrate 不匹配问题
• App Router 模式下，所有用到 styled-components 的组件都需要标记 'use client'，全局样式组件必须放在客户端组件内渲染
• 整个应用只需要实例化一次 createGlobalStyle，直接和根组件平级渲染即可，不需要嵌套在其他样式容器中
• 不要在全局样式里写过于具体的选择器，避免污染业务组件样式
• 不要在 createGlobalStyle 中使用除 theme 外的动态 props，否则会导致 hydrate 报错
• 如果出现刷新页面样式丢失问题，优先排查 next.config.js 配置是否正确开启了 styledComponents 支持

内容的提问来源于stack exchange，提问作者Ricardo de Paula