使用vitest preview搭配Tailwind遇CssSyntaxError：未知符号'>'

问题重现 #

使用以下命令预编译Tailwind CSS后：

tailwindcss -i ./src/styles/App.css -c tailwind.config.ts -o ./.vitest-preview/tailwind-output.css --autoprefixer

启动Vitest Preview时触发CssSyntaxError: [postcss] Unknown word错误，报错指向Tailwind生成的space-y-4工具类中的子组合器>：

.space-y-4 > :not([hidden]) ~ :not([hidden]) {
  --tw-space-y-reverse: 0;
  margin-top: calc(1rem * calc(1 - var(--tw-space-y-reverse)));
  margin-bottom: calc(1rem * var(--tw-space-y-reverse));
}

解决方案 #

方案1：让Vitest直接编译Tailwind CSS（推荐） #

放弃预编译CSS，让Vitest的处理链直接编译Tailwind，避免预编译后的语法兼容问题：

1. 确保安装了PostCSS相关依赖：

npm install -D postcss autoprefixer

2. 在项目根目录创建postcss.config.js：

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

3. 修改test-setup.ts，导入原始Tailwind入口文件而非预编译后的CSS：

import '@testing-library/jest-dom'

import '@fontsource/poppins'
import '@fontsource/poppins/400.css'
import '@fontsource/poppins/700.css'

// 替换为原始Tailwind入口CSS
import './src/styles/App.css'

4. 保持Vitest配置中css: true，确保CSS会被PostCSS处理。

方案2：生成兼容happy-dom的Tailwind CSS #

如果坚持使用预编译CSS，可修改Tailwind配置生成兼容低版本环境的语法：

1. 修改tailwind.config.ts，设置目标环境为IE11（会自动转换复杂选择器）：

export default {
  // 其他配置项
  target: 'ie11',
}

2. 重新运行Tailwind编译命令：

tailwindcss -i ./src/styles/App.css -c tailwind.config.ts -o ./.vitest-preview/tailwind-output.css --autoprefixer

方案3：更换DOM环境为jsdom #

happy-dom对部分CSS选择器支持不完善，可替换为对CSS支持更全面的jsdom：

1. 安装jsdom依赖：

npm install -D jsdom

2. 修改Vitest配置中的环境：

export default defineConfig({
    // 其他配置项
    test: {
        include: ['**/*.test.tsx'],
        environment: 'jsdom', // 替换为jsdom
        css: true,
        setupFiles: './test-setup.ts',
        globals: true,
    },
})

原因说明 #

报错本质是happy-dom内置的CSS解析器对>子组合器与:not伪类的组合语法支持不足，或是Vitest处理预编译CSS时缺少必要的PostCSS插件解析现代CSS语法。上述三种方案分别通过调整编译流程、生成兼容语法、更换DOM环境解决该问题。

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