UnoCSS 主包 unocss 完全指南：instant on-demand 原子化 CSS 引擎的聚合入口、特性与全生态集成实战

UnoCSS 主包 unocss 完全指南instant on-demand 原子化 CSS 引擎的聚合入口、特性与全生态集成实战【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocssUnoCSS 是一款即时按需生成的原子化 CSS 引擎instant on-demand Atomic CSS engine其官方发布的主包unocss是一个面向最终用户的聚合包meta package它一次性打包了核心引擎、全部官方预设与转换器并对外暴露 Vite、Nuxt、Astro、Webpack、PostCSS、CLI、CDN Runtime 等各集成入口。本文将基于本仓库中 packages-presets/unocss/README.md 与对应源码系统讲解unocss包的设计定位、核心特性、安装接入方式与真实配置示例读完你即可在自己的项目里落地这套按需原子化 CSS 方案。一、unocss 是什么聚合包背后的设计哲学在 npm 生态中unocss本仓库对应目录 packages-presets/unocss版本 66.10.0见 package.json是 UnoCSS 面向最终用户的唯一入口包。其description正是官方对项目本身的定位The instant on-demand Atomic CSS engine.——一个即时、按需生成的原子化 CSS 引擎。它的设计理念可以从两个层面理解“无核心工具类no core utilities”与 Tailwind 等把大量工具类硬编码进框架不同UnoCSS 默认不内置任何工具类所有功能全部通过**预设presets**提供。因此它是完全可定制的——你可以只启用需要的预设甚至完全自定义规则。相关配置体系见 docs/config/index.md 与 docs/guide/config-file.md。“不解析、不构建 AST、不扫描No parsing, no AST, no scanning”UnoCSS 通过极轻量的正则匹配从源码中抽取工具类 token规避了传统 CSS 框架生成时的解析开销从而获得极快的构建速度。从包结构看聚合包的职责非常清晰。以 src/index.ts 为例它集中完成了三件事export * from unocss/core转出核心引擎 API批量转出全部官方预设presetUno、presetWind、presetWind3、presetWind4、presetMini、presetAttributify、presetIcons、presetTagify、presetTypography、presetWebFonts批量转出官方转换器transformerAttributifyJsx、transformerCompileClass、transformerDirectives、transformerVariantGroup。同时 package.json 的exports字段暴露了./vite、./astro、./postcss、./webpack、./rollup、./rolldown以及./preset-*等子路径入口dependencies则聚合了unocss/core、unocss/vite、unocss/cli及各 preset/transformer 工作区包。也就是说用户只需安装一个unocss即可获得整套生态。二、核心特性逐一拆解README 中列举了该引擎最受关注的特性。以下逐条结合本仓库源码与文档说明其实质与用法。1. 完全可定制一切皆预设UnoCSS 没有核心工具类规则、变体、主题、快捷方式全部通过预设与配置注入。官方提供了presetUno、presetWind3、presetWind4、presetMini等工具类预设以及presetIcons、presetAttributify、presetWebFonts、presetTypography、presetTagify等能力预设详见 docs/config/presets.md 与 docs/guide/presets.md。2. INSTANT即时的性能表现官方 README 声称其速度是 Windi CSS 或 Tailwind JIT 的5 倍且包体仅约6kbminbrotli、零依赖、对浏览器友好。这些数字来自项目官方自述其根基在于无解析、无 AST、无扫描的极简匹配模型。仓库中 bench 目录保留了与 Tailwind CSS、Windi CSS 的基准对比用例fixtures 与历次 results 记录可供读者自行复现验证。3. Shortcuts动态别名工具类通过shortcuts配置可以把一组工具类合并为一个语义化名称并且支持动态规则。例如将flex items-center定义为center还可用函数式写法按参数生成组合。完整配置说明见 docs/config/shortcuts.md。4. Attributify 模式把工具类写进属性在 HTML/Vue 中可以用属性attributes来分组工具类例如div flex justify-center items-centerAttributify 模式允许将其改写为属性形式flex justify-center items-center的分散写法。实现位于 packages-presets/preset-attributify配套说明见 docs/presets/attributify.md。5. Pure CSS Icons一个类名即可使用任意图标presetIcons让你把任意图标集当作单个类使用例如i-carbon-search即可输出对应图标的纯 CSS以 mask/background 方式渲染无需引入字体或组件。实现见 packages-presets/preset-icons说明见 docs/presets/icons.md。6. Variant Groups公共前缀的简写把共享前缀的工具类分组书写例如把hover:bg-gray-100 hover:text-black写成hover:(bg-gray-100 text-black)。实现位于 packages-presets/transformer-variant-group说明见 docs/transformers/variant-group.md。7. CSS Directives在 CSS 中复用工具类通过apply指令在 CSS 文件里直接引用工具类例如.btn { apply px-4 py-2 rounded bg-blue-500 text-white; }实现位于 packages-presets/transformer-directives说明见 docs/transformers/directives.md。此外该转换器还支持screen等指令。8. Compilation 模式构建期把多个类合成一个transformerCompileClass可在构建时把多个工具类合并为一个自定义类名显著减小 HTML 体积适合对产物体积敏感的 MPA/SSR 场景。实现见 packages-presets/transformer-compile-class说明见 docs/transformers/compile-class.md。9. Inspector交互式检查与调试官方提供可视化 Inspector 面板可实时查看每个工具类生成的 CSS、规则命中情况与耗时统计。实现位于 packages-integrations/inspectorVue 3 Vite 构建的客户端使用说明见 docs/tools/inspector.md仓库内还有 examples/inspector-vite 与 examples/inspector-next 两个可直接运行的示例。10. CSS-in-JS Runtime 构建一行 CDN 引入通过 packages-integrations/runtime 提供的运行时方案只需一行 CDN 引入即可在纯浏览器环境无构建工具中使用 UnoCSS详见 docs/integrations/runtime.md。11. VS Code 扩展官方 VS Code 扩展提供工具类补全、悬停预览与检查功能源码位于 packages-integrations/vscode接入说明见 docs/integrations/vscode.md。12. CSS 代码分割为 MPA 输出最小化 CSS在 Vite 等构建集成中UnoCSS 针对多页面应用MPA做 CSS 代码分割每个页面只输出其实际使用到的样式避免首屏加载无关样式。相关机制说明见 docs/integrations/vite.md。三、安装与集成八大接入方式unocss聚合包官方提供以下集成路径对应 README 的 Installation 列表各集成说明见 docs/integrations/index.md集成方式使用场景仓库依据ViteVite 构建的项目最主流接入方式examples/inspector-vite/vite.config.ts、packages-integrations/viteNuxtNuxt 3/4 应用examples/nuxt3/nuxt.config.ts、packages-integrations/nuxtAstroAstro 站点examples/astro/astro.config.ts、packages-integrations/astroWebpackWebpack 构建的项目packages-integrations/webpackCDN Runtime无构建工具、一行 CDN 引入packages-integrations/runtimeCLI命令行生成 CSS配合任意构建流程packages-engine/cliVS Code 扩展编辑器内的补全与检查packages-integrations/vscodeESLint代码规范与静态检查packages-integrations/eslint-config、packages-integrations/eslint-pluginPostCSS通过 PostCSS 管道接入packages-integrations/postcssVite 接入示例最常用以 Vite 为例安装后在vite.config.ts中注册插件即可// vite.config.ts import UnoCSS from unocss/vite export default { plugins: [ UnoCSS(), ], }从 src/vite.ts 源码可以看到unocss/vite的默认导出在转发给unocss/vite时会自动注入presetWind3()作为默认预设export default function UnocssVitePlugin(configOrPath?) { return VitePlugin(configOrPath, { presets: [presetWind3()], }) }也就是说即便你不配置任何预设Vite 接入后也能直接使用presetWind3提供的工具类语法。同理src/astro.tsAstro 集成与src/rollup.tsRollup/Rolldown 集成默认同样注入presetWind3()而src/webpack.tsWebpack 集成默认注入的是presetUno()。这一开箱即用默认预设的设计正是聚合包降低上手成本的关键细节。四、真实配置文件示例defineConfig 与预设组合聚合包在 src/index.ts 中提供了类型安全的defineConfig辅助函数export function defineConfigT extends object Theme(config: UserConfigT) { return config }它与unocss/core的UserConfig类型配合让配置文件获得完整的类型提示。本仓库自身的 docs/uno.config.ts 就是一个可直接参考的真实示例import { defineConfig, presetAttributify, presetIcons, presetWind4, transformerDirectives } from unocss export default defineConfig({ theme: { animation: { keyframes: { custom: {0%, 100% { transform: scale(0.5); } 50% { transform: scale(1); }}, }, durations: { custom: 2s }, timingFns: { custom: cubic-bezier(0.4,0,.6,1) }, properties: { custom: { transform-origin: center } }, counts: { custom: infinite }, }, }, presets: [ presetWind4(), presetIcons(), presetAttributify(), ], transformers: [ transformerDirectives(), ], })这段配置演示了几个关键点预设组合同时启用presetWind4Wind 4 语法工具类、presetIcons图标、presetAttributify属性模式Transformer 编排通过transformerDirectives()开启apply等 CSS 指令能力主题扩展在theme.animation下自定义 keyframes、时长、缓动函数、属性和循环次数为animate-custom这类工具类提供数据源。更多配置项rules、variants、shortcuts、safelist、layers、extractors、processors分别见 docs/config/rules.md、docs/config/variants.md、docs/config/shortcuts.md、docs/config/safelist.md、docs/config/layers.md 与 docs/config/extractors.md。五、生态全景预设、转换器与包布局作为聚合包unocss依赖并汇总了本仓库packages-presets与packages-integrations两大目录下的全部核心模块工具类预设preset-mini基础原子预设、preset-unoUno 预设、preset-wind3兼容 Windi CSS 语法的 Wind 3、preset-wind4Tailwind CSS v4 风格语法能力预设preset-attributify、preset-icons、preset-tagify、preset-typography、preset-web-fonts转换器transformer-attributify-jsx、transformer-compile-class、transformer-directives、transformer-variant-group构建集成packages-integrations/vite、packages-integrations/rollup、packages-integrations/webpack、packages-integrations/postcss、packages-integrations/astro、packages-integrations/nuxt、packages-integrations/svelte-scoped 等工具链packages-integrations/inspector、packages-integrations/language-server、packages-integrations/vscode、packages-integrations/eslint-config 与 packages-integrations/eslint-plugin引擎与 CLIpackages-engine/core核心引擎与类型、packages-engine/cli、packages-engine/autocomplete工具类自动补全、packages-engine/config。各预设与转换器的独立用法与配置项可继续阅读 packages-presets/README.md 及各子包的 README。六、设计溯源与许可UnoCSS 的诞生受到多个原子化 CSS 先行者的启发README 的 Acknowledgement 部分明确致谢了以下项目按字母序ACSS、Bootstrap Utilities、Chakra UI Style Props、Semantic UI、Tachyons、Tailwind CSS、Twind 与 Windi CSS。其核心按需生成、不扫描 AST、极致轻量的取舍正是针对这些方案在产物体积与构建速度上的不足而设计。本包遵循MIT协议见 LICENSEREADME 中标明 © 2021-PRESENT Anthony Fu。UnoCSS 的完整官方文档、交互式文档、在线 Playground 与教程均可在其官网获得在本仓库内docs/index.md 是文档的本地入口playground 目录提供了可在浏览器中运行的在线体验实现。七、总结unocss聚合包以一切皆预设、即时按需生成为核心通过一个安装包即可覆盖从 Vite/Nuxt/Astro/Webpack 等构建集成到 CLI/PostCSS/运行时/CDN 等轻量方案再到 VS Code、ESLint、Inspector 等开发工具链的完整生态。理解其默认预设注入零核心工具类纯正则抽取这三条设计主线是正确配置与调优的前提而本仓库中 src/index.ts、src/vite.ts 等入口源码与 docs/uno.config.ts 示例则是从源码层面验证这些行为的最佳参考。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考