React.ts+Vite项目中index.css的Tailwind @theme不被识别求助

问题描述 #

基于React.ts、Vite和Tailwind CSS v4搭建项目时，尝试在index.css文件中通过@theme语法自定义断点与颜色变量，但该语法未被识别。index.css中的:root等其他CSS规则可正常生效，查阅官方文档及相关视频未找到解决方案，推测为操作失误导致。

相关代码文件 #

index.css #

@import "tailwindcss";

:root {
    font-family: dm-sans, sans-serif;
    font-size: 16px;
    line-height: 1.5;
    color: var(--color-gray-100);
    background-color: var(--color-gray-800);
}

@theme {
    --breakpoint-*: initial;
    --breakpoint-sm: 480px;
    --breakpoint-md: 768px;
    --breakpoint-lg: 976px;

    --color-gray-100: #f5f5f5;
    --color-gray-200: #e0e0e0;
}

package.json #

{
  "name": "app-youtube",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "@tailwindcss/vite": "^4.0.8",
    "class-variance-authority": "^0.7.1",
    "lucide-react": "^0.475.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "tailwind-merge": "^3.0.2",
    "tailwindcss": "^4.0.8"
  },
  "devDependencies": {
    "@eslint/js": "^9.19.0",
    "@types/react": "^19.0.8",
    "@types/react-dom": "^19.0.3",
    "@vitejs/plugin-react": "^4.3.4",
    "eslint": "^9.19.0",
    "eslint-plugin-react-hooks": "^5.0.0",
    "eslint-plugin-react-refresh": "^0.4.18",
    "globals": "^15.14.0",
    "typescript": "~5.7.2",
    "typescript-eslint": "^8.22.0",
    "vite": "^6.1.0"
  },
  "require": {
    "esbuild": "0.25.0"
  }
}

vite.config.ts #

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
})

解决方案 #

Tailwind CSS v4中@theme语法的使用场景有限，官方更推荐通过配置文件自定义主题变量，以下是正确的实现步骤：

1. 创建Tailwind配置文件 #

在项目根目录新建tailwind.config.ts，将自定义的断点和颜色变量写入配置：

import { defineConfig } from 'tailwindcss';

export default defineConfig({
  theme: {
    extend: {
      // 自定义断点
      screens: {
        sm: '480px',
        md: '768px',
        lg: '976px',
      },
      // 自定义颜色
      colors: {
        gray: {
          100: '#f5f5f5',
          200: '#e0e0e0',
          800: '#121212', // 补充你在:root中使用的gray-800色值
        },
      },
    },
  },
});

2. 修改index.css文件 #

移除@theme代码块，改用Tailwind提供的theme()函数引用配置好的变量，或直接使用生成的CSS变量：

@import "tailwindcss";

:root {
    font-family: dm-sans, sans-serif;
    font-size: 16px;
    line-height: 1.5;
    color: theme('colors.gray.100');
    background-color: theme('colors.gray.800');
}

3. 验证配置 #

重启Vite开发服务，此时自定义的断点和颜色变量会被Tailwind正确识别，你可以在组件中直接使用如text-gray-100、md:flex这类类名，或通过var(--color-gray-100)引用CSS变量。

说明 #

Tailwind CSS v4的@theme语法主要用于CSS模块或CSS-in-JS场景，在全局CSS文件中直接使用时需要额外配置预处理器解析规则，而通过配置文件自定义主题是官方推荐的标准方式，更易维护且兼容性更好。

内容的提问来源于stack exchange，提问作者markCos0