Tailwind 主题配置需模块化拆分并统一用 extend 包裹自定义项，避免顶层键覆盖；所有模块须 CommonJS 导出，禁止 import 交叉引用，theme.js 仅聚合 theme 对象供 tailwind.config.js 引入。
大规模项目里，Tailwind 的主题配置不能堆在 tailwind.config.js 一个文件里——它会迅速变成难以维护的“配置泥潭”，协作时改个颜色都要全局 grep，CI 构建也变慢。核心解法是模块化拆分 + 显式依赖管理。
tailwind.config.js 中如何正确引入模块化配置
直接 require 多个 JS 文件是可行的，但必须注意导出结构和合并逻辑。Tailwind 的 theme 是深度合并（deep merge），不是浅覆盖，所以 extend 和顶层键行为不同。
-
colors、fontSize、spacing等顶层键若在多个模块中定义，后加载的会完全覆盖前一个（非合并） -
extend下的字段才是安全合并的，比如extend.colors.brand和extend.spacing['1/7']可以分散在不同文件里 - 推荐统一用
extend包裹所有自定义项，哪怕只是单个值，避免意外覆盖 - 模块路径建议用相对路径，如
require('./config/tailwind/colors')，而非../config/...，防止重构时路径断裂
为什么 colors.js 里要返回对象而不是直接 module.exports = {...}
因为 Tailwind 内部调用的是 require() 后的值，如果 colors.js 里用了 module.exports = { primary: { ... } }，那它就是一个 plain object；但如果用了 module.exports = () => ({...}) 或 export default（ESM），就会报错或静默失效。
- 确保所有配置模块都是 CommonJS 导出：
module.exports = { ... } - 不要在
colors.js里 import 其他模块（比如typography.js），容易引发循环依赖 - 如果需要复用基础色值（如
gray-50），建议提取到config/tailwind/tokens.js单独导出，再被各模块 require
如何让 theme.js 和 tailwind.config.js 协同工作
很多团队误以为 theme.js 是 Tailwind 的标准配置入口，其实它只是你自己的封装层。真正生效的是 tailwind.config.js 里最终导出的对象。
立即学习“前端免费学习笔记（深入）”；
-
theme.js应该只做一件事：聚合所有模块并返回完整 theme 对象，不包含content、plugins等非 theme 字段 -
tailwind.config.js中只需theme: require('./config/theme')，其余字段（content、plugins）仍保留在 config 文件里 - 禁止在
theme.js里写module.exports = { theme: { ... } }，这会让 Tailwind 读不到 theme - 开发时可加一层校验：在
theme.js末尾console.log('✅ theme loaded')，启动 dev server 时快速确认是否加载成功
最易被忽略的是模块加载顺序和 deep merge 的边界——extend 是安全区，顶层键是雷区。一旦把 spacing 拆到两个文件里分别导出，就必然有一个被丢弃，而错误不会报在终端，只会默默失效。
