css主题文件必须使用.module.css后缀才能实现按需加载，因react不支持非模块化css的tree-shaking或条件加载；裸css如theme-dark.css会被全局注入，无法按需；应定义为独立css modules文件，仅含局部类且无:global；动态加载需用loading状态兜底并避免ssr失败。
主题CSS文件必须用 .module.css 后缀才能按需加载
React 本身不支持直接 import 非模块化 CSS 文件并让它参与构建时的 tree-shaking 或运行时条件加载。如果你写的是 theme-dark.css 这种裸 CSS，Webpack/Vite 默认会把它当成全局样式一次性注入，无法“按需”——哪怕你用 import() 动态导入，它也会立即执行并污染全局 scope。
正确做法是把每个主题定义为独立的 CSS Modules 文件：theme-dark.module.css、theme-light.module.css。它们内部只写局部类（如 .root、.header），不带 :global，也不依赖外部类名。
- 模块化后，
import()返回的是一个 Promise，resolve 出来的是带哈希键的对象，可安全用于 className 绑定 - Vite 会自动将
import('./theme-dark.module.css')编译为异步 chunk；Webpack 也原生支持（需启用css-loader的 modules 模式） - 别试图在
.css里写:root { --color-bg: #111; }然后靠 JS 切换——那不是“按需加载 CSS”，只是切换变量值，文件本身仍被全量加载
import() 动态加载后怎么安全注入到组件中
CSS Modules 导出的是对象，不是字符串，不能直接 document.head.appendChild。你真正要做的，是让组件“感知”新样式对象，并用它生成 className。
典型错误：在 useEffect 里调用 import('./theme-dark.module.css').then(...)，然后把结果存进 state，再在 JSX 中写 className={styles.root}——这会导致首次渲染时 styles 是 undefined，报错或样式丢失。
- 必须用 loading 状态兜底，比如初始
const [themeStyles, setThemeStyles] = useState(null)，渲染时判断!themeStyles ? <div classname="skeleton"></div> : <div classname="{themeStyles.root}"></div> - 避免在函数组件顶层写
import()，它不是同步语句，会破坏 React 的渲染一致性 - 如果主题切换频繁（比如用户快速点两次），记得用
AbortController或标记位取消前一次 pending 的import()，否则可能 setState 到已卸载组件上
如何避免主题类名和基础组件类名冲突
很多人把主题样式和组件样式混在一个文件里，比如 Button.module.css 里既写 .base 又写 .theme-dark，结果导致主题切换时 Button 自己的样式也被覆盖或失效。
主题应只负责“皮肤层”：颜色、间距比例、阴影强度等通用变量级样式；组件自身结构、尺寸、交互态（:hover、:focus）必须由组件自己的 CSS Modules 控制。
- 主题文件里只定义根级修饰类，例如
.theme-dark .container、.theme-light .text，且所有选择器都以.theme-xxx开头 - 组件 JSX 中用双重 className：
className={`${themeStyles?.root || ''} ${buttonStyles.base}`，而不是把主题类硬塞进组件样式对象里 - 千万别在主题文件里写
:global(.ant-btn) { ... }——这等于主动放弃 CSS Modules 的隔离性，后续维护成本爆炸
服务端渲染（SSR）下动态主题加载会失败
Node.js 环境不支持动态 import()（除非用 dynamic-import-node 插件），所以 import('./theme-dark.module.css') 在 SSR 阶段会抛 ReferenceError: document is not defined 或直接返回空对象。
这不是 bug，是设计使然：主题是客户端行为，不该在首屏就决定。但你要处理好降级逻辑。
- SSR 时默认使用 fallback 主题（比如 light），通过
getInitialProps或getServerSideProps注入一个初始theme='light'prop - 客户端水合（hydration）完成后，再触发
import()加载真实主题，用useLayoutEffect确保样式替换发生在 DOM 渲染前 - 如果用了 Next.js，注意
dynamic(importer, { ssr: false })可以跳过 SSR 阶段的 import，但主题样式仍需提前通过next/head注入一个最小 light 主题 CSS，否则首屏白屏或错色
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
