执行npm run build构建TailwindCSS v4项目时遇意外')' CSS语法错误

问题重现 #

执行npm run build时出现两个异常：

1. CSS语法错误：Unexpected ")"，指向:where()选择器位置
2. 空Chunk警告：Generated an empty chunk: "app"

报错详情：

npm run build

> build
> vite build

vite v6.2.5 building for production...
✓ 2 modules transformed.
Generated an empty chunk: "app".
rendering chunks (1)...warnings when minifying css:
▲ [WARNING] Unexpected ")" [css-syntax-error]

    <stdin>:7:153265:
      7 │ ...or:var(--color-zinc-100)}:where(){width:calc(var(--spacing)*5);h...
        ╵                                    ^


public/build/manifest.json              0.27 kB │ gzip:  0.14 kB
public/build/assets/app--Cil65mr.css  190.86 kB │ gzip: 26.36 kB
public/build/assets/app-l0sNRNKZ.js     0.00 kB │ gzip:  0.02 kB
✓ built in 607ms

当前package.json配置：

{
    "private": true,
    "type": "module",
    "scripts": {
        "build": "vite build",
        "dev": "vite dev",
        "watch": "vite build --watch"
    },
    "dependencies": {
        "@tailwindcss/vite": "^4.1.1",
        "autoprefixer": "^10.4.21",
        "axios": "^1.8.4",
        "concurrently": "^9.1.2",
        "laravel-vite-plugin": "^1.2.0",
        "tailwindcss": "^4.1.1",
        "vite": "^6.2.5"
    },
    "optionalDependencies": {
        "@rollup/rollup-linux-x64-gnu": "4.39.0",
        "@tailwindcss/oxide-linux-x64-gnu": "^4.1.1",
        "lightningcss-linux-x64-gnu": "^1.29.3"
    }
}

修复方案 #

1. 解决CSS语法错误 #

原因

Tailwind CSS 4.x依赖的lightningcss（oxide编译器）对空:where()选择器的语法处理存在兼容性问题，或是版本不匹配导致的解析异常。

解决步骤

• 方案一：回退到稳定的Tailwind 3.x版本
  4.x属于迭代中的版本，兼容性不如3.x稳定，执行以下命令降级：

  npm uninstall tailwindcss @tailwindcss/vite
  npm install tailwindcss@^3.4.1 @tailwindcss/vite@^0.2.1
  

• 方案二：更新依赖并修正语法（若坚持用4.x）

  1. 更新lightningcss到最新版本：

     npm update lightningcss-linux-x64-gnu
     

  2. 检查Tailwind配置或自定义CSS中是否存在空:where()选择器（如:where(){...}），替换为合法的选择器（比如:where(html){...}）。
  3. 清除缓存并重装依赖：

     npm cache clean --force
     rm -rf node_modules package-lock.json
     npm install
     

2. 解决空Chunk警告 #

原因

Vite检测到app入口的JS文件没有实际可执行代码（仅导入CSS或无内容），因此生成空的JS chunk。

解决步骤

• 方案一：给入口JS添加基础代码
  在resources/js/app.js中加入任意合法JS代码，避免空文件：

  // 示例：基础初始化代码
  document.addEventListener('DOMContentLoaded', () => {
      console.log('Application loaded');
  });
  

• 方案二：调整Vite构建配置
  修改vite.config.js，禁用自动分块或指定输出规则：

  import { defineConfig } from 'vite';
  import laravel from 'laravel-vite-plugin';
  
  export default defineConfig({
      plugins: [
          laravel({
              input: ['resources/css/app.css', 'resources/js/app.js'],
              refresh: true,
          }),
      ],
      build: {
          rollupOptions: {
              output: {
                  manualChunks: undefined, // 关闭自动分块
              },
          },
      },
  });
  

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