使用TailwindCSS v4时IntelliSense无法检测错误类名的问题

问题描述 #

我从TailwindCSS v3开始使用TailwindCSS IntelliSense VSCode插件，近期通过create-next-app创建了Next.js 15项目，采用TailwindCSS v4。插件的自动补全、悬停预览功能正常，也能检测invalidConfigPath、invalidScreen、emptyRoles这类错误，例如：

.example {
  color: theme('colors.redd.50')
}

@screen small {}
@variant group {}

但无法检测JSX中拼写错误的Tailwind类名，比如：

<div className="bg-bule-500"></div>

已知eslint-plugin-tailwindcss仅支持TailwindCSS v3，不兼容v4，想了解这种情况是否正常，以及有没有办法在VSCode或CLI中检测错误类名。

相关配置文件 #

./vscode/settings.json

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "tailwindCSS.validate": true,
  "tailwindCSS.includeLanguages": {
    "javascript": "javascript",
    "typescript": "typescript",
    "javascriptreact": "javascriptreact",
    "typescriptreact": "typescriptreact"
  },
  "tailwindCSS.experimental.classRegex": [],
  "tailwindCSS.experimental.configFile": "app/globals.css",
  "tailwindCSS.classAttributes": [
    "class",
    "className",
    "ngClass",
    "class:list"
  ],
  "editor.quickSuggestions": {
    "other": "on",
    "comments": "off",
    "strings": "on"
  }
}

/app/globals.css（已被根layout.tsx导入）

@import "tailwindcss";

:root {
  --background: #ffffff;
  --foreground: #171717;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;
    --foreground: #ededed;
  }
}

body {
  background: var(--background);
  color: var(--foreground);
  font-family: Arial, Helvetica, sans-serif;
}

/postcss.config.mjs

const config = {
  plugins: ['@tailwindcss/postcss'],
};

export default config;

package.json（部分内容）

{
  "dependencies": {
    "clsx": "^2.1.1",
    "react": "19.1.0",
    "react-awesome-reveal": "^4.3.1",
    "react-dom": "19.1.0",
    "react-hook-form": "^7.58.0",
    "react-icons": "^5.5.0",
    "tailwind-merge": "^3.3.1",
    "tailwindcss-animate": "^1.0.7"
  },
  "devDependencies": {
    "@eslint/eslintrc": "^3.3.1",
    "@next/eslint-plugin-next": "^15.3.3",
    "@tailwindcss/postcss": "^4.1.10",
    "@tailwindcss/typography": "^0.5.16",
    "@types/node": "^22.15.31",
    "@types/react": "19.1.4",
    "@types/react-dom": "19.1.5",
    "@typescript-eslint/eslint-plugin": "^8.34.0",
    "@typescript-eslint/parser": "^8.34.0",
    "eslint": "^9.29.0",
    "eslint-config-next": "^15.3.3",
    "eslint-plugin-next": "^0.0.0",
    "eslint-plugin-react": "^7.37.5",
    "eslint-plugin-react-hooks": "^5.2.0",
    "postcss": "^8.5.5",
    "tailwindcss": "^4.1.10",
    "tw-animate-css": "^1.3.4",
    "typescript": "^5.8.3",
    "typescript-eslint": "^8.34.0"
  }
}

（注：项目无tailwind.config.ts文件，符合TailwindCSS v4架构要求）

解答 #

1. 这种情况是否正常？ #

是的。TailwindCSS v4采用了全新的内联主题架构，取消了传统的tailwind.config.ts配置文件，而TailwindCSS IntelliSense插件目前对v4的适配还在迭代中，暂时只完善了CSS代码中的错误检测，JSX/TSX里的类名拼写错误校验功能尚未完全适配v4的新结构。

2. 检测错误类名的可行方案 #

VSCode编辑器端

• 更新插件版本：确保TailwindCSS IntelliSense是最新版，官方后续会逐步补充v4的类名校验支持。
• 优化类名识别配置：在settings.json中添加自定义类名正则，帮助插件更精准识别JSX中的类名：

  "tailwindCSS.experimental.classRegex": [
    ["className=\"([^\"]*)\"", "\"([^\"]*)\""],
    ["class=\"([^\"]*)\"", "\"([^\"]*)\""]
  ]
  

  部分场景下可触发错误提示，但效果可能有限。
• 依赖自动补全：保持editor.quickSuggestions开启（你已配置），尽量通过插件的自动补全功能输入类名，从源头避免拼写错误。

CLI命令行端

TailwindCSS v4自带lint命令，可直接检测无效类名：

• 运行检测命令：

  npx tailwindcss lint
  

  命令会扫描项目代码，输出所有无效的Tailwind类名。
• 集成到脚本：在package.json中添加脚本，方便快速调用：

  "scripts": {
    "lint:tailwind": "npx tailwindcss lint"
  }
  

  之后执行npm run lint:tailwind即可完成检测。

其他临时手段

• 用tailwind-merge过滤无效类名：虽然这是运行时处理，无法在编辑/编译时提示，但能确保无效类名不会被渲染到页面。
• TypeScript类型约束：尝试使用tailwindcss-types生成类名类型定义（需自行适配v4），给TSX中的className字段添加类型校验，在编写代码时触发类型错误提示。

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