主题颜色变量未生效的四大原因：变量定义位置错误、构建流程未读取新配置、css选择器权重不足、运行时主题切换未清除旧样式缓存，需逐一排查。
主题颜色变量是否被正确覆盖
很多 CSS 框架（如 Tailwind、Ant Design、Element Plus）用 CSS 自定义属性或预处理器变量控制主题色，但改了变量值却没生效，大概率是变量没在正确位置定义，或被后续样式覆盖。比如 Tailwind 的 theme.extend.colors 必须写在 tailwind.config.js 里，而不是直接在 CSS 中重写 --tw-color-primary；而 Ant Design 的 @primary-color 必须在 less 变量文件中修改，并确保该文件在组件样式前 import。
- 检查变量定义位置：Tailwind →
tailwind.config.js；AntD →ant-design-vars.less；Element Plus →el-variables.scss - 确认构建流程是否读取了新配置：改完
tailwind.config.js后需重启 dev server；改 less/scss 变量后需确保样式入口文件重新编译 - 避免在组件内用
style或内联color: #1890ff硬编码，会绕过主题系统
CSS 优先级是否被更高权重的选择器压制
即使变量生效，生成的 CSS 规则也可能被更具体的选择器覆盖。比如框架组件内部用了 .btn-primary:hover，而你只写了 .btn-primary，hover 状态下颜色就回退到默认值；或者第三方 UI 库的 CSS 文件被后引入，导致你的主题样式被覆盖。
- 用浏览器开发者工具检查目标元素，看最终生效的
color/background-color来自哪条规则，注意!important和选择器特异性（如div .btn.primary比.btn-primary权重高） - Tailwind 默认不加 !important，若需强制覆盖，可在
tailwind.config.js中启用important: true，或用!text-red-500手动标记 - 确保主题 CSS 文件在 HTML 中
<link>的顺序靠前，或在 webpack/vite 配置中调整样式加载顺序
运行时主题切换是否清除了旧样式缓存
部分框架（如 antd v5+、naive-ui）支持运行时动态换肤，依赖 CSS-in-JS 注入或 style 标签替换。如果手动修改了变量但页面没刷新，或切换主题后颜色卡在旧值，很可能是旧的 style 标签未被移除，或 CSS 变量未被更新到 :root。
- 检查是否调用了正确的 API：AntD 用
theme.useToken()+ConfigProvider；Naive UI 用useThemeVars()；不要只改 JS 变量却不触发样式重渲染 - 确认
:root下的 CSS 变量（如--primary-color）是否已更新：在 Elements 面板选中，看 computed 样式里的变量值 - Vite/HMR 场景下，less/scss 热更新有时不触发全局变量重计算，可临时加个空格保存变量文件强制刷新
深色模式或媒体查询干扰了主题色显示
有些框架默认为深色模式提供独立变量（如 @primary-color-dark），或通过 @media (prefers-color-scheme: dark) 覆盖颜色。你以为改了主色，实际页面正运行在暗色上下文中，走的是另一套变量分支。
立即学习“前端免费学习笔记（深入）”；
- 在 DevTools 的 Rendering 面板中临时禁用
prefers-color-scheme，看颜色是否恢复正常 - 检查框架文档是否要求同时设置明/暗双模式变量，例如 Element Plus 的
$--color-primary-dark和$--color-primary-light - 避免在 CSS 中用
@media手动覆盖主题色，除非明确知道当前主题上下文，否则容易冲突
