直接修改 document.documentelement.dataset.theme 是最快最轻量的主题切换方案，因其不触发 react 渲染、无序列化限制且由浏览器原生 gpu 加速执行，配合预置 css 变量规则即可实现零闪动瞬切。
直接改 document.documentElement.dataset.theme 是最快、最轻量的方案，但如果你已用 styled-components 或 emotion，用它们的 ThemeProvider 也能跑通——只是得接受额外的 React 渲染开销和主题对象序列化限制。
为什么不用 CSS-in-JS 的 ThemeProvider 切换主题？
因为 ThemeProvider 本质是靠 Context + React 渲染树重传主题对象，每次 setTheme 都会触发所有消费 props.theme 的 styled 组件重新计算样式、re-render。哪怕你只改一个颜色变量，Button、Card、Input 全部跟着 rerender。这不是“样式切换”，是“组件批量刷新”。
更麻烦的是：主题对象不能含函数、Symbol、DOM 节点等非 JSON-safe 值；一旦你往主题里塞了 transition: 'all 0.2s' 这类带单位的字符串，某些库（比如旧版 styled-components）会在 SSR 时序列化失败，报 TypeError: Do not know how to serialize a BigInt 类似错误。
- 主题对象必须是纯 JSON 可序列化的结构
- 所有依赖
props.theme的 styled 组件都会参与 diff 和 re-render - 无法实现真正的 0 毫秒切换——GPU 不介入，全靠 JS 主线程推样式
如果坚持用 styled-components，怎么最小化副作用？
核心思路是：把主题变量“降级”为 CSS Custom Properties，让 ThemeProvider 只负责注入根节点的 data-theme 属性，不传复杂对象。CSS 规则写在外部 .css 文件里，而不是靠 JS 动态生成。
示例做法：
- 定义
lightTheme和darkTheme仅为字符串'light'/'dark'，不是颜色对象 - 在
index.css中写：:root[data-theme="light"] { --bg: #fff; --text: #000; }和:root[data-theme="dark"] { --bg: #111; --text: #eee; } - styled 组件里只用
color: var(--text)，不再读props.theme.text -
ThemeProvider变成空壳，仅用于透传data-theme到根节点
这样既保留了 styled-components 的开发体验，又把样式计算交还给浏览器原生机制。
emotion 用户要注意的兼容性陷阱
emotion 的 css 函数默认支持 var(--xxx)，但如果你用了 @emotion/react 的 Global 注入全局样式，且在 SSR 环境中运行，必须确保 Global 的内容在服务端和客户端完全一致。否则会出现 hydration mismatch，控制台报 Prop `data-emotion` did not match。
常见翻车点：
- 在
Global里动态拼接 CSS 字符串（如css\`:root { --primary: ${theme.primary}; }\`），SSR 时theme是初始值，CSR 后才更新，导致首屏样式错乱 - 用
useInsertionEffect动态插入<style></style>标签，但没做服务端跳过逻辑 -
createCache实例未在 SSR 和 CSR 间复用，导致 emotion 生成的 class 名不一致
真正零闪动的主题切换，只靠一行 JS
别绕弯子。现代浏览器对 :root[data-theme] 的响应是原生的、GPU 加速的。你只需要这一行：
document.documentElement.dataset.theme = 'sunset'
配合预置好的 CSS 变量规则，就能完成从「鼠尾草绿」到「暖陶落日」的瞬切。React 不需要知道这事发生了，也不需要 rerender 任何组件。那些想用 useThemeSwitcher Hook 封装一切的人，往往卡在“如何让这个 Hook 在服务端也生效”上——其实根本不用它。
最容易被忽略的一点：dataset.theme 的值必须和 CSS 选择器里的字符串完全一致，大小写、连字符、空格都不能差。写成 data-theme="Sunset" 而 CSS 里是 [data-theme="sunset"]，就彻底失效。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
