本教程提供了在 Vue CLI 4.x 项目中正确配置 UnoCSS 的步骤，避免常见的配置错误。

1. 安装依赖

执行以下命令安装必要的依赖：

npm install @unocss/webpack --save-dev
npm install unocss --save-dev

推荐的版本：

{
  "devDependencies": {
    "unocss": "^0.46.5",
    "@unocss/webpack": "^0.46.5"
  }
}

2. 配置 vue.config.js

注意：这是关键步骤，很多教程在这里有错误！

在 vue.config.js 中正确配置 UnoCSS：

const unocss = require('@unocss/webpack').default

module.exports = {
  // ⚠️ 重要：css 配置必须在顶层，不能放在 configureWebpack 内部
  css: {
    extract: {
      filename: '[name].[hash:9].css'
    }
  },
  configureWebpack: {
    plugins: [
      unocss()  // 注意：不需要 new 关键字
    ]
  }
}

❌ 错误的配置方式：

// 这样配置会导致 webpack 报错
module.exports = {
  configureWebpack: {
    plugins: [
      unocss()
    ],
    css: {  // ❌ 错误：css 配置不能放在这里
      extract: {
        filename: '[name].[hash:9].css'
      }
    }
  }
}

✅ 正确的配置方式：

// 正确的配置结构
module.exports = {
  css: {  // ✅ 正确：css 配置在顶层
    extract: {
      filename: '[name].[hash:9].css'
    }
  },
  configureWebpack: {
    plugins: [
      unocss()  // ✅ 正确：插件配置在这里
    ]
  }
}

3. 创建 unocss.config.js

在项目根目录创建 unocss.config.js 文件：

import {
  defineConfig,
  presetAttributify,
  presetUno,
  transformerDirectives,
} from 'unocss'

export default defineConfig({
  rules: [
    [/^line-height-(.+)$/, ([, d]) => ({ 'line-height': `${+d / 4}rem` })],
  ],
  shortcuts: [
    // 可以在这里定义快捷样式
  ],
  presets: [
    presetUno(),
    presetAttributify(),
  ],
  transformers: [
    transformerDirectives(),
    // transformerVariantGroup(),
  ],
})

4. 在 main.js 中引入样式

在 src/main.js 文件中添加 UnoCSS 样式引入：

import Vue from 'vue'
import 'normalize.css/normalize.css'
import 'uno.css'  // 添加这行来引入 UnoCSS 样式

// 其他导入...

5. 测试配置

创建一个测试页面验证 UnoCSS 是否正常工作：

<template>
  <div>
    <div class="text-red-500 text-lg font-bold">
      UnoCSS 测试：红色大字体
    </div>
    <div class="bg-blue-100 p-4 m-2 rounded">
      UnoCSS 测试：蓝色背景卡片
    </div>
    <div class="flex items-center justify-center h-20 bg-gray-200">
      UnoCSS 测试：Flex 布局
    </div>
  </div>
</template>

6. 启动项目

npm run dev

如果遇到缓存问题，可以尝试：

1. 删除 node_modules 文件夹
2. 删除 package-lock.json 文件
3. 重新安装依赖：npm install
4. 重启 VS Code

常见问题解决

问题 1: WebpackOptionsValidationError - configuration has an unknown property ‘css’

原因： css 配置被错误地放在了 configureWebpack 内部。

解决方案： 将 css 配置移到顶层，如上面正确配置所示。

问题 2: UnoCSS 样式不生效

可能原因和解决方案：

1. 确保在 main.js 中引入了 'uno.css'
2. 检查 unocss.config.js 文件是否正确配置
3. 重启开发服务器
4. 重启 VS Code
5. 清除浏览器缓存

问题 3: 构建时出现错误

解决方案：

1. 确保 UnoCSS 版本兼容
2. 检查 webpack 插件配置是否正确
3. 查看是否有其他插件冲突

验证安装成功

如果以上测试样式能够正确显示（红色文字、蓝色背景、Flex 布局），说明 UnoCSS 已经成功配置并运行。

注意事项

1. Vue CLI 版本兼容性： 本教程适用于 Vue CLI 4.x，其他版本可能需要调整配置
2. webpack 配置： 确保理解 Vue CLI 的配置结构，避免将配置放在错误的位置
3. 样式冲突： 注意 UnoCSS 与其他 CSS 框架（如 Element UI）的样式冲突
4. 生产构建： 确保在生产环境中样式也能正确提取和压缩

总结

主要修正点：

• css 配置位置： 必须放在 vue.config.js 的顶层，不能放在 configureWebpack 内
• 插件配置： unocss() 不需要 new 关键字
• 依赖版本： 确保使用兼容的版本
• 样式引入： 在 main.js 中正确引入 ‘uno.css’

遵循本教程可以避免常见的配置错误，成功在 Vue CLI 4.x 项目中使用 UnoCSS。