首页-所有文章-Nuxt.js,Vue.js-正文

Nuxt 4 中 Naive UI 集成与 UnoCSS 原子化样式实战

龙霄

Nuxt.js , Vue.js

9天前

3.03K

本文详解如何在 Nuxt 4 项目中高效集成 Naive UI 组件库与 UnoCSS 原子化 CSS 引擎，涵盖自动导入配置、SSR 样式收集、Vite 构建优化和分包策略，实现零手动引入、按需加载的极致开发体验。

在大型 Nuxt 4 项目中，如何高效集成 Naive UI 组件库，并与 UnoCSS 原子化 CSS 引擎协同工作？

一、为什么选择 Naive UI + UnoCSS？

维度	Naive UI	UnoCSS
定位	企业级 Vue 3 组件库	按需原子化 CSS 引擎
体积	Tree-shaking 按需加载	零运行时，只生成用到的规则
TypeScript	原生 TypeScript 编写	规则预设类型安全
主题	内置亮色/暗色主题	与 Naive UI 主题变量互通
SSR	@css-render/vue3-ssr 支持	内联 CSS 无额外开销

二、Naive UI 自动导入配置

第一步：Vite 插件

plugins: [
    AutoImport({
        imports: [{
            'naive-ui': [
                'createDiscreteApi', 'useOsTheme', 'useMessage', 'useDialog',
                'lightTheme', 'darkTheme', 'zhCN', 'zhTW', 'dateZhCN', 'dateZhTW'
            ]
        }]
    }),
    Components({ resolvers: [NaiveUiResolver()] })
]

第二步：SSR 支持

{ "dependencies": { "@css-render/vue3-ssr": "^0.15.14" } }

第三步：转译配置

build: { transpile: ['naive-ui', 'vueuc', 'radash'] }

离散 API 的全局注入

const { message, dialog } = createDiscreteApi(['message', 'dialog'])
;(globalThis as any).__salongMessage = message

三、UnoCSS 架构

Nuxt Layers 整合

unocss: { nuxtLayers: true }

SCSS 与原子化 CSS 的分工

Naive UI 主题变量 → custom.scss（变量覆盖）
全局布局/重置 → main.scss
组件级定制样式 → UnoCSS 原子类（class="flex items-center gap-4 p-4"）

CSS Directives 转换器

.my-card {
    @apply bg-white rounded-lg shadow-md p-4 hover:shadow-lg transition-shadow;
}

四、Vite 优化配置

vite: {
    optimizeDeps: {
        include: ['naive-ui', 'vueuc', 'dayjs', 'dompurify', 'vidstack/player', ...]
    },
    build: {
        minify: 'esbuild',           // 比 terser 快 20-40 倍
        cssMinify: true,
        assetsInlineLimit: 4096,     // 小于 4KB 内联
        rollupOptions: {
            output: {
                manualChunks(id) {
                    if (id.includes('node_modules/@vue-office')) {
                        const pkg = id.match(/@vue-office\\/([^/]+)/)?.[1]
                        return pkg ? `vue-office-${pkg}` : 'vue-office'
                    }
                }
            }
        }
    }
}

五、性能最佳实践

优化项	做法	效果
组件按需加载	NaiveUiResolver 自动解析	只打包用到的组件
内联小资源	assetsInlineLimit: 4096	减少 HTTP 请求
分包策略	manualChunks 按库拆分	提升缓存命中率
依赖预构建	optimizeDeps.include 白名单	加速冷启动
esbuild 压缩	minify: 'esbuild'	构建速度显著提升
禁用内联样式	features.inlineStyles: false	减少 SSR HTML 体积