在 tailwind.config.js 中需将 CSS 变量作为值注入 theme.extend.colors 等合法键下（如 primary: 'var(--primary-color)'），而非直接定义变量名；变量须在全局 CSS 中预设，并配合 :root、.dark 或 prefers-color-scheme 实现响应式与深色模式切换。
tailwind.config.js 中怎么用 theme.extend 注入 CSS 变量
直接在 theme.extend 里写 CSS 变量（如 --primary-color）不会生效——Tailwind 不解析变量名，它只把值转成类的声明。正确做法是把变量作为「值」塞进已有属性键下，让生成的工具类引用它。
比如你想用 var(--primary-color) 控制背景色，不能这么写：
extend: {
colors: {
'--primary-color': 'var(--primary-color)' // ❌ 无效：Tailwind 不会识别这个键为颜色
}
}而应该绑定到一个真实可用的颜色别名上：
extend: {
colors: {
primary: 'var(--primary-color)',
secondary: 'var(--secondary-color)'
}
}这样你就能在 HTML 中写 bg-primary，最终编译出的 CSS 会是 background-color: var(--primary-color);
立即学习“前端免费学习笔记（深入）”；
- 必须确保
theme.extend.colors.primary这类键名是合法标识符（不能含连字符、括号等） - 变量名本身（
--primary-color）需在全局 CSS 中提前定义，例如在@tailwind base之前用:root声明 - 如果变量带计算（如
calc(var(--base-size) * 1.2)），Tailwind 也能原样透传，但运行时依赖浏览器支持
如何让自定义 CSS 变量支持响应式和深色模式
Tailwind 本身不“感知” CSS 变量的变化，所以响应式或深色模式下的变量切换，得靠你自己在 CSS 层级控制。常见组合是：:root 定义默认值，@media (prefers-color-scheme: dark) 或 .dark 类覆盖变量值，再配合 Tailwind 工具类引用这些变量。
示例流程：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 在
src/index.css中，@tailwind base之前写：
:root {
--primary-color: #3b82f6;
--bg-color: #ffffff;
}
@media (prefers-color-scheme: dark) {
:root {
--primary-color: #60a5fa;
--bg-color: #111827;
}
}
.dark {
--primary-color: #818cf8;
--bg-color: #1f2937;
}- 然后在
tailwind.config.js中扩展：
theme: {
extend: {
colors: {
primary: 'var(--primary-color)',
bg: 'var(--bg-color)'
}
}
}最后在 HTML 中用 bg-bg text-primary，并手动切换 document.documentElement.classList.add('dark') 或依赖系统偏好。
- 注意：不要指望
dark:bg-primary自动读取.dark下的--primary-color——它只是把var(--primary-color)塞进.dark .bg-primary的声明里，真正起作用的是你前面定义的.dark对变量的重设 - 若用
prefers-color-scheme，记得在<html>上加class="dark"或不加，由浏览器自动匹配
为什么 addUtilities + CSS 变量容易导致 PurgeCSS 漏删
当你用 addUtilities 手动注入带 var(--x) 的规则（比如 '.text-brand': { color: 'var(--brand-text)' }），Tailwind 的 content 扫描机制无法识别这种间接引用——它只认 HTML 中显式的类名字符串，比如 text-brand。如果模板里没出现 text-brand，PurgeCSS 就会把它整个干掉，哪怕你 CSS 文件里明明白白写了。
- 解决方案一：在
content配置中加一条兜底路径，比如"./src/styles/tailwind-utilities.css"，里面放所有你手写的addUtilities类名的空引用（<div class="text-brand"></div>） - 解决方案二：改用
theme.extend+ 工具类（如text-brand映射到theme('colors.brand.text')），这样 PurgeCSS 能通过配置文件推断使用关系 - 最稳妥的做法：避免在
addUtilities里写变量，除非你明确关闭了 PurgeCSS 或接受全量输出
自定义属性与插件中 theme() 函数的配合陷阱
在插件函数里调用 theme('colors.primary')，拿到的是配置中写死的字符串值（比如 #3b82f6），不是 var(--primary-color)。如果你在 theme.extend.colors.primary 里填的是 'var(--primary-color)'，那 theme() 返回的就是这个字符串，它会被原样插入到生成的 CSS 中——这本身没问题，但要注意上下文是否允许。
比如这个插件写法：
addUtilities({
'.shadow-brand': {
'box-shadow': `0 4px 6px -1px ${theme('colors.primary')}`
}
})如果 theme('colors.primary') 是 var(--primary-color)，那最终生成的 CSS 就是 box-shadow: 0 4px 6px -1px var(--primary-color);，完全合法。但如果你后续想用这个 shadow 做响应式变体（如 md:shadow-brand），就得确认插件里是否手动加了媒体查询包裹，否则它只会生成基础版本。
- 插件中的
theme()是静态快照，不随运行时变量变化；变量的实际值由浏览器在渲染时计算 - 不要在插件里对
var(--x)做字符串拼接运算（如calc(${theme('colors.primary')} * 0.8)），CSS 不支持这种语法 - 若需动态计算，应交由 CSS 自身完成（如
color-mix(in srgb, var(--primary-color), white 30%)），Tailwind 只负责透传
变量声明位置、PurgeCSS 行为、插件中 theme() 的求值时机——这三个点一旦串错，就会出现「配置写了但样式不生效」「深色模式切换后颜色不变」「构建后类名消失」这类典型静默失败。它们不报错，但结果不可控。
