多语言与多主题按需加载依赖分层解耦、运行时注入和构建期静态分析协同；组件须剥离i18n/theme实现，通过context接收t函数和token；语言包/主题配置需拆为独立chunk并由app侧动态加载；css主题应通过css变量+js注入实现ssr友好切换；组件内需轻量校验上下文缺失并文档强调provider包裹要求。
直接说结论：多语言 + 多主题 + 按需加载不是靠“堆功能”实现的，而是靠分层解耦 + 运行时注入 + 构建期静态分析三者协同。核心矛盾不在代码写多少，而在模块边界划在哪、谁负责加载、谁负责切换。
如何让组件不硬编码语言和样式，只声明依赖
组件自身必须剥离 i18n 和 theme 的具体实现。比如一个 Button 不能直接调用 useI18n() 或读取 theme.primary，而应通过 props 或 context 接收翻译函数和主题 token。
- 推荐用 React 的
useContext配合两个 Provider：I18nContext（提供t函数）和ThemeContext（提供tokens对象） - 避免在组件内部 import 全量语言包或主题配置 —— 这会阻断按需加载，导致所有语言/主题被打包进主 bundle
- 组件导出时保留原始形态，例如
export const Button = (props) => {...}，不包裹withI18n或styled(Button)
怎么实现语言包和主题的真正按需加载
关键在构建工具链配合运行时逻辑：语言包和主题配置必须是独立 chunk，且加载时机由业务侧控制，而非组件库强制触发。
- 语言包按 locale 拆成单独文件，如
zh-CN.js、en-US.js，导出纯对象，不带副作用；构建时设为 dynamic import 的目标，例如import(`./locales/${locale}.js`) - 主题配置同理，每个主题一个
theme-dark.js、theme-high-contrast.js，内容仅包含 token 映射，不包含 CSS-in-JS 注入逻辑 - 禁止在组件库入口（如
index.ts）中 import 任何 locale 或 theme 文件 —— 否则 Webpack/Vite 会把它们全打进 initial chunk - 实际加载由上层 App 触发，并通过 Provider 注入，组件库只消费，不拉取
为什么 CSS 主题切换不能只靠 class 切换
单纯给 body 加 theme-dark class 并配全局 CSS 规则，在多主题 + SSR + 按需加载场景下极易出问题：样式未就绪时组件已渲染、服务端无主题上下文、CSS 优先级冲突等。
- 推荐用 CSS 变量 + JS 注入方式：主题包导出的是变量映射对象（如
{ '--color-bg': '#1a1a1a', '--color-text': '#eee' }），由统一的applyTheme()函数写入document.documentElement.style - 确保该函数可被多次调用，且能 diff 变更项（避免重复 setProperty），否则频繁切换主题会导致重排
- SSR 时需在服务端同步注入初始主题变量，否则首屏闪动；可通过
renderToPipeableStream或renderToStaticMarkup前调用applyTheme(initTheme)实现
按需加载组件时，怎么避免语言/主题能力丢失
当用户用 import { Button } from 'ui/Button' 单独引入组件，很容易忽略上下文依赖 —— 这时候组件会渲染，但文字为空、颜色错乱，错误又不报，极难排查。
- 在组件内部加轻量级校验：比如
if (!t || typeof t !== 'function') console.warn('[ui] missing I18nContext')，不 throw（避免崩溃），但给出明确提示 - 文档里必须强调使用前提：“所有组件依赖
I18nProvider和ThemeProvider，请确保其包裹在应用根节点” - 提供最小可用 demo 脚手架（含正确 Provider 嵌套结构），而不是只放单个组件用法
- 注意：Babel 插件（如
babel-plugin-import）默认不处理 context 引用，所以即使你写了按需加载，Provider 仍需手动引入 —— 这点常被忽略
最难的部分不是实现多语言或多主题，而是让它们彼此隔离、各自可替换、加载时机可控。一旦把 locale 数据、theme token、CSS 注入、context 提供者这几层混在一起，后面所有按需加载和动态切换都会变成补丁叠补丁。
