createGlobalStyle 返回的是需挂载的 React 组件，必须在应用顶层（如 _app.tsx）以 JSX 渲染；不支持直接执行、useEffect 调用或条件渲染，且动态主题需显式声明函数签名并透传 theme。
createGlobalStyle 必须作为组件挂载，不能直接执行
它返回的是一个 React 组件，不是立即生效的样式注入函数。常见错误是写完 createGlobalStyle`body { margin: 0 }` 就以为完事了，结果页面没变化——因为根本没渲染这个组件。
正确做法是把它当普通组件用 JSX 渲染，且必须出现在应用最顶层（比如 App 或 _app.tsx 的根节点内）：
import { createGlobalStyle } from 'styled-components';
const GlobalStyle = createGlobalStyle`
body {
margin: 0;
background: ${props => props.theme.bg || '#fff'};
}
`;
function App() {
return (
<>
<GlobalStyle theme={{ bg: '#f0f0f0' }} />
<main>...</main>
</>
);
}
- ❌ 不要放在
useEffect里调用，SSR 时不会执行 - ❌ 不要条件渲染，如
{isReady && <globalstyle></globalstyle>}，首屏会 FOUC - ✅ 挂载位置越靠上越好，Next.js 中必须在
_app.tsx的Component外层包裹
动态主题变量必须显式声明参数并传入
createGlobalStyle 默认不自动读取 ThemeProvider 提供的 theme，也不能在模板字符串里直接写 ${props.theme.color} 而不声明函数签名。
写法必须是函数式，并在 JSX 中透传 theme：
立即学习“前端免费学习笔记（深入）”；
const GlobalStyle = createGlobalStyle(({ theme }) => `
:root {
--primary: ${theme.primary};
}
body {
color: ${theme.text};
background: ${theme.bg};
}
`);
- ✅ 在组件中使用：
<GlobalStyle theme={theme} /> - ❌ 错误：
createGlobalStyle`body { color: ${props.theme.text}; }`（props未定义） - ⚠️ 如果只是静态重置（如
margin: 0），用纯字符串更轻量，不用函数形式
多个 createGlobalStyle 实例按挂载顺序覆盖同名规则
它生成的 <style data-styled="gbl"> 标签按 React 挂载顺序插入 <head>，后挂载的会覆盖先挂载的同名 CSS 属性——这和原生 CSS 层叠一致，但容易被忽略。
- ✅ 推荐：把所有 reset、字体、CSS 变量统一写在一个实例里，避免拆散
- ⚠️ 风险：第三方 UI 库（如某些设计系统）自带
createGlobalStyle，可能意外覆盖你的body font-size或:root变量 - ? 检查方式：打开 DevTools → Elements → 查看
<head>中的<style data-styled="gbl">标签顺序和内容
SSR 场景下必须首屏即渲染，否则触发 FOUC
服务端渲染时，如果 GlobalStyle 组件没在初始 HTML 中输出，客户端 hydration 后才补上样式，会导致页面闪白或布局跳动。
- ✅ Next.js：
_app.tsx中直接渲染，不可包裹在if (typeof window !== 'undefined')或自定义 Hook 内 - ✅ Remix：
root.tsx的Outlet上方顶层渲染 - ❌ 常见坑：用
useIsomorphicLayoutEffect或延迟加载逻辑控制显示，SSR 阶段完全跳过 - ? 真正难点不在怎么写，而在于「谁负责确保它第一时间挂载」——通常得由框架入口文件或根 Layout 承担这个责任
