Vue3项目实战5分钟搞定Unocss配置含暗黑模式适配在Vue3生态中原子化CSS正在成为提升开发效率的新范式。Unocss作为下一代原子化CSS引擎以其极致的灵活性和近乎零配置的体验正在快速取代传统的TailwindCSS。本文将带你从零开始在Vite驱动的Vue3项目中快速集成Unocss并通过实战案例展示如何利用原子化样式构建现代化界面特别包含开发者最关心的暗黑模式无缝切换方案。1. 环境准备与基础配置1.1 创建Vue3项目使用Vite初始化一个TypeScript版本的Vue3项目npm create vitelatest unocss-demo --template vue-ts cd unocss-demo npm install1.2 安装Unocss核心依赖npm install -D unocss unocss/vite unocss/preset-uno这三个包构成了Unocss的核心unocss: 核心引擎unocss/vite: Vite插件unocss/preset-uno: 默认预设包含Tailwind兼容规则2. Vite配置集成2.1 修改vite.config.ts在项目根目录的vite.config.ts中添加Unocss插件import { defineConfig } from vite import vue from vitejs/plugin-vue import Unocss from unocss/vite import { presetUno } from unocss export default defineConfig({ plugins: [ vue(), Unocss({ presets: [presetUno()] }) ] })2.2 创建Unocss配置文件虽然可以直接在Vite配置中定义Unocss规则但为了更好的可维护性建议创建独立的配置文件uno.config.tsimport { defineConfig, presetUno } from unocss export default defineConfig({ presets: [ presetUno({ dark: class // 启用暗黑模式 }) ], shortcuts: { btn: px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600, card: p-6 rounded-lg shadow-md bg-white dark:bg-gray-800 } })提示dark: class配置表示暗黑模式将通过HTML元素的classdark来触发3. 项目结构适配3.1 引入Unocss样式在main.ts或main.js中导入Unocssimport virtual:uno.css3.2 配置VS Code智能提示安装Unocss官方VS Code插件在项目根目录创建.vscode/settings.json{ unocss.root: ., unocss.include: [src/**/*.{vue,ts,js}] }4. 暗黑模式实现方案4.1 基础切换逻辑在App.vue中实现暗黑模式切换script setup import { ref } from vue const isDark ref(false) const toggleDark () { isDark.value !isDark.value document.documentElement.classList.toggle(dark, isDark.value) } /script template button clicktoggleDark classfixed top-4 right-4 btn {{ isDark ? ☀️ : }} /button router-view / /template4.2 暗黑模式样式编写Unocss的暗黑模式前缀为dark:使用方式如下div classtext-gray-800 dark:text-gray-200 bg-white dark:bg-gray-900 !-- 内容 -- /div4.3 持久化存储方案结合localStorage实现状态持久化// utils/darkMode.ts export function useDarkMode() { const isDark ref(localStorage.getItem(darkMode) true) const toggleDark () { isDark.value !isDark.value localStorage.setItem(darkMode, String(isDark.value)) document.documentElement.classList.toggle(dark, isDark.value) } onMounted(() { document.documentElement.classList.toggle(dark, isDark.value) }) return { isDark, toggleDark } }5. 实战组件案例5.1 卡片组件实现template div classcard max-w-md mx-auto my-8 h2 classtext-xl font-bold mb-4 text-gray-800 dark:text-gray-100 {{ title }} /h2 p classtext-gray-600 dark:text-gray-300 {{ content }} /p button classbtn mt-4 查看详情 /button /div /template script setup defineProps({ title: String, content: String }) /script5.2 响应式导航栏template nav classflex items-center justify-between p-4 bg-white dark:bg-gray-800 shadow div classtext-2xl font-bold text-blue-600 dark:text-blue-400 Logo /div div classhidden md:flex space-x-6 a v-foritem in navItems :keyitem.name href# classtext-gray-700 dark:text-gray-300 hover:text-blue-500 dark:hover:text-blue-400 {{ item.name }} /a /div button classmd:hidden div classi-carbon-menu text-2xl/div /button /nav /template script setup const navItems [ { name: 首页, path: / }, { name: 产品, path: /products }, { name: 关于, path: /about } ] /script6. 高级配置技巧6.1 自定义规则扩展在uno.config.ts中添加自定义规则export default defineConfig({ rules: [ [text-shadow, { text-shadow: 0 2px 4px rgba(0,0,0,0.1) }], [/^custom-(\d)$/, ([, d]) ({ padding: ${d}px })] ] })6.2 图标集成方案安装图标预设npm install -D unocss/preset-icons iconify/json配置图标预设import { presetIcons } from unocss/preset-icons export default defineConfig({ presets: [ presetUno(), presetIcons({ scale: 1.2, extraProperties: { display: inline-block, vertical-align: middle } }) ] })使用方式div classi-carbon-settings text-2xl text-blue-500/div6.3 性能优化配置export default defineConfig({ content: { pipeline: { exclude: [node_modules, dist, .git, .vscode] } }, safelist: [ text-red-500, text-green-500, text-blue-500 ] })7. 常见问题解决7.1 样式不生效检查清单确保已安装所有必要依赖检查vite.config.ts是否正确配置Unocss插件确认main.ts中导入了virtual:uno.css查看浏览器控制台是否有构建错误尝试重启开发服务器7.2 生产环境构建优化vite build --mode production构建后检查确认dist/assets目录下生成了Unocss样式文件检查HTML文件是否正确引用了生成的CSS7.3 VS Code智能提示不工作确保已安装Unocss VS Code插件检查.vscode/settings.json配置是否正确重启VS Code确保文件类型为.vue或.ts
Vue3项目实战：5分钟搞定Unocss配置（含暗黑模式适配）
发布时间：2026/7/10 4:15:25
Vue3项目实战5分钟搞定Unocss配置含暗黑模式适配在Vue3生态中原子化CSS正在成为提升开发效率的新范式。Unocss作为下一代原子化CSS引擎以其极致的灵活性和近乎零配置的体验正在快速取代传统的TailwindCSS。本文将带你从零开始在Vite驱动的Vue3项目中快速集成Unocss并通过实战案例展示如何利用原子化样式构建现代化界面特别包含开发者最关心的暗黑模式无缝切换方案。1. 环境准备与基础配置1.1 创建Vue3项目使用Vite初始化一个TypeScript版本的Vue3项目npm create vitelatest unocss-demo --template vue-ts cd unocss-demo npm install1.2 安装Unocss核心依赖npm install -D unocss unocss/vite unocss/preset-uno这三个包构成了Unocss的核心unocss: 核心引擎unocss/vite: Vite插件unocss/preset-uno: 默认预设包含Tailwind兼容规则2. Vite配置集成2.1 修改vite.config.ts在项目根目录的vite.config.ts中添加Unocss插件import { defineConfig } from vite import vue from vitejs/plugin-vue import Unocss from unocss/vite import { presetUno } from unocss export default defineConfig({ plugins: [ vue(), Unocss({ presets: [presetUno()] }) ] })2.2 创建Unocss配置文件虽然可以直接在Vite配置中定义Unocss规则但为了更好的可维护性建议创建独立的配置文件uno.config.tsimport { defineConfig, presetUno } from unocss export default defineConfig({ presets: [ presetUno({ dark: class // 启用暗黑模式 }) ], shortcuts: { btn: px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600, card: p-6 rounded-lg shadow-md bg-white dark:bg-gray-800 } })提示dark: class配置表示暗黑模式将通过HTML元素的classdark来触发3. 项目结构适配3.1 引入Unocss样式在main.ts或main.js中导入Unocssimport virtual:uno.css3.2 配置VS Code智能提示安装Unocss官方VS Code插件在项目根目录创建.vscode/settings.json{ unocss.root: ., unocss.include: [src/**/*.{vue,ts,js}] }4. 暗黑模式实现方案4.1 基础切换逻辑在App.vue中实现暗黑模式切换script setup import { ref } from vue const isDark ref(false) const toggleDark () { isDark.value !isDark.value document.documentElement.classList.toggle(dark, isDark.value) } /script template button clicktoggleDark classfixed top-4 right-4 btn {{ isDark ? ☀️ : }} /button router-view / /template4.2 暗黑模式样式编写Unocss的暗黑模式前缀为dark:使用方式如下div classtext-gray-800 dark:text-gray-200 bg-white dark:bg-gray-900 !-- 内容 -- /div4.3 持久化存储方案结合localStorage实现状态持久化// utils/darkMode.ts export function useDarkMode() { const isDark ref(localStorage.getItem(darkMode) true) const toggleDark () { isDark.value !isDark.value localStorage.setItem(darkMode, String(isDark.value)) document.documentElement.classList.toggle(dark, isDark.value) } onMounted(() { document.documentElement.classList.toggle(dark, isDark.value) }) return { isDark, toggleDark } }5. 实战组件案例5.1 卡片组件实现template div classcard max-w-md mx-auto my-8 h2 classtext-xl font-bold mb-4 text-gray-800 dark:text-gray-100 {{ title }} /h2 p classtext-gray-600 dark:text-gray-300 {{ content }} /p button classbtn mt-4 查看详情 /button /div /template script setup defineProps({ title: String, content: String }) /script5.2 响应式导航栏template nav classflex items-center justify-between p-4 bg-white dark:bg-gray-800 shadow div classtext-2xl font-bold text-blue-600 dark:text-blue-400 Logo /div div classhidden md:flex space-x-6 a v-foritem in navItems :keyitem.name href# classtext-gray-700 dark:text-gray-300 hover:text-blue-500 dark:hover:text-blue-400 {{ item.name }} /a /div button classmd:hidden div classi-carbon-menu text-2xl/div /button /nav /template script setup const navItems [ { name: 首页, path: / }, { name: 产品, path: /products }, { name: 关于, path: /about } ] /script6. 高级配置技巧6.1 自定义规则扩展在uno.config.ts中添加自定义规则export default defineConfig({ rules: [ [text-shadow, { text-shadow: 0 2px 4px rgba(0,0,0,0.1) }], [/^custom-(\d)$/, ([, d]) ({ padding: ${d}px })] ] })6.2 图标集成方案安装图标预设npm install -D unocss/preset-icons iconify/json配置图标预设import { presetIcons } from unocss/preset-icons export default defineConfig({ presets: [ presetUno(), presetIcons({ scale: 1.2, extraProperties: { display: inline-block, vertical-align: middle } }) ] })使用方式div classi-carbon-settings text-2xl text-blue-500/div6.3 性能优化配置export default defineConfig({ content: { pipeline: { exclude: [node_modules, dist, .git, .vscode] } }, safelist: [ text-red-500, text-green-500, text-blue-500 ] })7. 常见问题解决7.1 样式不生效检查清单确保已安装所有必要依赖检查vite.config.ts是否正确配置Unocss插件确认main.ts中导入了virtual:uno.css查看浏览器控制台是否有构建错误尝试重启开发服务器7.2 生产环境构建优化vite build --mode production构建后检查确认dist/assets目录下生成了Unocss样式文件检查HTML文件是否正确引用了生成的CSS7.3 VS Code智能提示不工作确保已安装Unocss VS Code插件检查.vscode/settings.json配置是否正确重启VS Code确保文件类型为.vue或.ts
