Vite+Tailwind项目自定义CSS中@tailwind报未知at规则错误如何解决

问题复现代码 #

项目入口main.js：

import "./styles.css";
// import "tailwindcss/tailwind.css";

document.querySelector("#app").innerHTML = `
  <h1>Hello Vite!</h1>
  <a href="#" target="_blank">Documentation</a>
`;

全局样式文件styles.css：

@tailwind base;
@tailwind components;
@tailwind utilities;

.header-nav-section {
  @apply bg-gradient-to-br from-gray-100e to-gray-300;
}

表现为VS Code弹出错误提示：Unknown at rule @tailwindcss(unknownAtRules)。

问题原因 #

三个独立问题可能同时触发报错：

• VS Code原生CSS校验不识别Tailwind自定义的@tailwind、@apply规则，属于编辑器静态校验误报，不影响项目实际运行。
• 缺少Tailwind对接Vite的必要依赖和配置，构建阶段无法识别@tailwind指令，会导致运行时样式完全失效。
• 样式类名存在笔误：from-gray-100e不是Tailwind内置色值，Tailwind默认灰色档位为50/100/200/300一直到900，不存在100e这个档位，就算编辑器报错消失，这个渐变样式也无法正常生效。
• 注：main.js里注释掉import "tailwindcss/tailwind.css"的写法没有问题，使用@tailwind指令配合PostCSS做按需构建是官方推荐用法，不需要修改。

解决步骤 #

1. 处理VS Code误报，二选一即可：
   • 安装Tailwind官方VS Code插件Tailwind CSS IntelliSense，安装完成后重启VS Code，插件会自动识别项目内的Tailwind配置，接管CSS语法校验，报错会直接消失，同时自带类名自动补全、语法高亮能力。
   • 不想安装插件的话，在项目根目录新建.vscode/settings.json文件，写入以下配置，让VS Code跳过CSS未知at规则检查：

     {
       "css.lint.unknownAtRules": "ignore"
     }
     

2. 补全构建配置（仅项目运行时样式也失效时需要操作）
   安装必要依赖：

   npm install -D tailwindcss postcss autoprefixer
   

   执行初始化命令生成Tailwind和PostCSS配置文件：

   npx tailwindcss init -p
   

   打开生成的tailwind.config.js，配置content扫描路径，指定Tailwind需要扫描类名的文件范围：

   /** @type {import('tailwindcss').Config} */
   export default {
     content: [
       "./index.html",
       "./src/**/*.{js,ts,jsx,tsx}",
     ],
     theme: {
       extend: {},
     },
     plugins: [],
   }
   

   配置完成后重启Vite开发服务即可。
3. 修复样式笔误
   把错误的色值类from-gray-100e改为合法的Tailwind色值类，例如from-gray-100，修正后的样式代码：

   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   .header-nav-section {
     @apply bg-gradient-to-br from-gray-100 to-gray-300;
   }
   

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