UnoCSS 配置文件完全指南：从 uno.config.ts 编写到源码级加载机制

UnoCSS 配置文件完全指南从 uno.config.ts 编写到源码级加载机制【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocssUnoCSS 是一个即时按需生成的原子化 CSS 引擎而配置文件是驾驭其全部能力的核心入口。本文围绕docs/guide/config-file.md展开讲解 UnoCSS 推荐的项目级配置文件uno.config.ts的编写方式、自动发现与手动指定机制、完整配置项说明并结合当前仓库的源码实现packages-engine/config、packages-engine/core、packages-integrations/vite剖析配置加载、HMR 热更新与错误恢复的底层原理让读者既能写出可运行的完整配置也能理解配置是如何被各集成工具消费的。为什么 UnoCSS 强烈推荐独立的配置文件UnoCSS 官方文档docs/guide/config-file.md的第一条建议就是强烈推荐使用专门的uno.config.ts文件来配置 UnoCSS。与把配置内联写在vite.config.ts或其他工具配置里相比独立配置文件能带来三方面直接收益IDE 与工具链的完整支持VS Code 扩展、LSP 语言服务等工具可以独立定位并解析配置文件从而提供智能提示、跳转定义、自动补全等能力见 VS Code 集成跨工具复用同一份配置可以被 ESLint 插件、CLI、Webpack、Rollup、PostCSS 等不同集成共享避免在多个配置文件里重复维护更好的 HMR 体验配置变更可以被开发服务器监听并触发热重载无需手动重启。配置文件命名与自动发现默认情况下UnoCSS 会在项目根目录自动查找以下文件名任意一种即可uno.config.{js,ts,mjs,mts} unocss.config.{js,ts,mjs,mts}也就是说uno.config.ts、uno.config.js、unocss.config.mjs、unocss.config.mts等都是合法的候选名。这一约定在配置加载器源码中得到了印证——packages-engine/config/src/index.ts 通过unconfig库创建加载器时明确传入了unocss.config与uno.config两个基础文件名const loader createLoaderU({ sources: isFile ? [{ files: resolved, extensions: [] }] : [ { files: [unocss.config, uno.config] }, ...extraConfigSources, ], cwd, })如果既没有配置文件也没有传入内联配置加载器会打印错误提示并回退到默认配置见同一文件 第 70-72 行[unocss/config] Config file not found in cwd - loading default config.一份功能完整的配置文件示例官方文档给出了一份功能齐全的配置模板uno.config.ts它基本涵盖了日常项目所需的全部核心区块import { defineConfig, presetAttributify, presetIcons, presetTypography, presetWebFonts, presetWind3, transformerDirectives, transformerVariantGroup, } from unocss export default defineConfig({ shortcuts: [ // 将多个工具类组合为语义化简写如 btn - py-2 px-4 font-semibold rounded-lg // ... ], theme: { colors: { // 自定义主题变量如 brand: #ff0000可被规则与变体引用 // ... }, }, presets: [ presetWind3(), presetAttributify(), presetIcons(), presetTypography(), presetWebFonts({ fonts: { // 配置字体来源如 sans: Roboto、mono: [Fira Code, Fira Mono:400,700] // ... }, }), ], transformers: [ transformerDirectives(), transformerVariantGroup(), ], })各区块的作用简要说明如下配置区块作用详细参考shortcuts组合多个工具类成一个新的简写类后者优先级更高Shortcuts 配置theme定义规则与变体共享的主题变量颜色、间距、断点等Theme 配置presets预设的配置集合按需启用 Wind3、Attributify、Icons 等能力Presets 配置、预设总览transformers对源码做变换以支持指令、变体分组等写法约定Transformers 配置presetWind3()提供与 Tailwind CSS 兼容的默认工具类集presetAttributify()支持在 HTML/Vue 中用属性写法使用工具类presetIcons()将图标名称解析为图标字体或 SVGpresetTypography()提供排版排版样式presetWebFonts()负责按需加载 Web 字体。这些预设均可从unocss单一入口导入见 packages-presets/unocss/src/index.ts。当前仓库的 examples/vite-vue3/uno.config.ts 就是一个真实可运行的示例其中展示了shortcuts中定义logo简写、通过presetIcons的collections挂载本地图标目录FileSystemIconLoader等实战写法。defineConfig类型安全的配置助手配置示例中的defineConfig是 UnoCSS 提供的类型辅助函数它不做任何运行时处理纯粹返回传入的配置对象核心价值是提供完整的 TypeScript 类型推断与校验。其定义位于 packages-presets/unocss/src/index.tsexport function defineConfigT extends object Theme(config: UserConfigT) { return config }UserConfig类型定义在 packages-engine/core/src/types.ts它由ConfigBase、UserOnlyOptions、GeneratorOptions、PluginOptions、CliOptions组合而成覆盖了从规则到 CLI 的全部配置维度。各集成本身也提供各自的defineConfig重载例如 Vite 集成在 packages-integrations/vite/src/index.ts 导出的defineConfig接受VitePluginConfig可额外获得 Vite 专属选项的类型提示。手动指定配置文件configFile 选项如果配置文件不在项目根目录或需要按环境区分多份配置可以通过集成工具的configFile选项手动指定路径。官方文档以 Vite 为例import UnoCSS from unocss/vite import { defineConfig } from vite export default defineConfig({ plugins: [ UnoCSS({ configFile: ../my-uno.config.ts, }), ], })configFile的取值类型为string | false见 packages-engine/core/src/types.ts传入文件路径字符串加载该文件且路径可以是相对项目根的如上例../my-uno.config.ts传入false完全禁用配置文件加载只使用内联配置。在loadConfig的实现中packages-engine/config/src/index.ts当传入的配置对象带configFile: false时会直接短路返回内联配置if (typeof configOrPath ! string) { hasUserCustomConfig true inlineConfig configOrPath if (inlineConfig.configFile false) { return { config: inlineConfig as U, sources: [] } } else { configOrPath inlineConfig.configFile || process.cwd() } }反过来如果手动指定的路径带.ts/.js/.mjs/.cjs/.mts扩展名却不存在加载器会抛出明确错误第 43-45 行[unocss/config] Custom config file not found: path. Please check the path and try again.该错误提示会以青色cyan高亮显示路径便于快速定位问题。配置项全景一份可查阅的参考地图docs/config/index.md汇总了所有顶层配置项及其类型、默认值。理解这些选项有助于写出更精确的配置配置项类型默认值说明rulesRuleTheme[]-定义原子 CSS 工具类后定义者优先级更高shortcutsUserShortcutsTheme-组合已有工具类为简写themeTheme-规则间共享的主题对象extendThemeArrayableThemeExtenderTheme-以函数方式变更主题也可返回全新主题对象整体替换variantsVariantTheme[]-预处理选择器可重写 CSS 对象extractorsExtractor[]-从源文件中提取候选类名可感知语言preflightsPreflightTheme[]-注入全局原始 CSSlayersRecordstring, number0各工具类层的排序outputToCssLayersboolean \| UseCssLayersOptionsfalse是否输出到 CSS Cascade LayerssortLayers(layers: string[]) string[]-自定义层排序函数presets(PresetOrFactory \| PresetOrFactory[])[]-常用场景的预设集合transformersSourceCodeTransformer[]-源码变换器processorsCSSProcessorTheme[]-在生成 CSS 暴露前对其做变换详见 ProcessorsblocklistBlocklistRule[]-排除选择器收窄设计系统范围safeliststring[]-始终包含的工具类preprocess/postprocessArrayablePreprocessor/ArrayablePostprocessor-工具类进入 / 生成对象之后的钩子separatorsArrayablestring[:, -]变体分隔符extractorDefaultExtractor \| null \| falsedefaultExtractor默认提取器传null/false可关闭autocomplete对象-自定义自动补全模板、提取器与简写contentContentOptions-提取工具类用法的内容来源文件系统 / 内联 / 构建管道各来源结果合并configResolved(config) void-配置解析完成后的钩子configFilestring \| false-配置文件路径false禁用configDepsstring[]-额外触发配置重载的文件列表shortcutsLayerstringshortcutsshortcuts 所在层名envModedev \| buildbuild环境模式detailsboolean-暴露内部细节便于调试/检查warnbooleantrueblocklist 命中时是否告警其中content是精细化控制提取范围的关键types.tscontent.filesystem支持 glob 模式默认忽略node_modules开发模式下文件被监听并触发 HMRcontent.pipeline控制是否从 Vite/Webpack 的转换管道中提取模块默认include覆盖vue/svelte/jsx/tsx/vine/mdx/astro/elm/php/html等.ts/.js默认不提取exclude默认排除css/scss/less/stylus等样式文件。源码视角配置加载与合并的完整链路从源码可以还原配置加载的完整调用链入口各集成如 Vite 插件、CLI把配置对象或路径传给loadConfig。Vite 插件的入口见 packages-integrations/vite/src/index.ts它会根据NODE_ENV自动设置envMode为dev或build上下文创建createContextvirtual-shared/integration/src/context.ts内部通过createRecoveryConfigLoader创建可容错的加载器第 40 行并在reloadConfig中依次完成加载配置 → 检查废弃用法deprecationCheck→ 记录sources配置文件列表→ 调用uno.setConfig(rawConfig)应用配置第 44-66 行合并顺序在 packages-engine/config/src/index.ts 中最终配置按defaults → inlineConfig → 文件配置的顺序合并Object.assign即配置文件中的值会覆盖内联配置内联配置覆盖默认值依赖文件如果配置中声明了configDeps这些文件路径会被解析为绝对路径后追加进sources第 76-81 行意味着它们变更时同样会触发配置重载。configDeps的典型用途是把主题 JSON、品牌变量文件等外部数据声明为配置依赖改动它们无需重启开发服务器。开发模式下的容错与热更新错误恢复createRecoveryConfigLoader开发过程中配置出现语法错误是常事。createRecoveryConfigLoaderpackages-engine/config/src/index.ts专门为此设计当加载失败时返回上一次成功加载的配置而不是让整个开发服务器崩溃export function createRecoveryConfigLoaderU extends UserConfig() { let lastResolved: LoadConfigResultU | undefined return async (cwd, configOrPath, extraConfigSources, defaults) { try { const config await loadConfig(cwd, configOrPath, extraConfigSources, defaults) lastResolved config return config } catch (e) { if (lastResolved) { consola.error([unocss/config] Error loading config:, e) return lastResolved } throw e } } }这一机制的意义在于你在编辑uno.config.ts的过程中即使写出了半成品或错误代码应用仍然能基于最近一次可用的配置继续运行。HMR配置文件变更即热重载Vite 集成中的ConfigHMRPluginpackages-integrations/vite/src/config-hmr.ts把配置文件纳入开发服务器监听configureServer阶段把sources配置文件及其依赖加入server.watcher任一文件被修改时调用ctx.reloadConfig()重新加载并应用配置随后通过 WebSocket 向客户端广播unocss:config-changed事件通知页面相关模块更新。同时该插件在configResolved阶段会调用ctx.updateRoot(config.root)同步项目根目录第 8-10 行并在configureServer中把envMode切换为dev第 14 行。这也解释了为什么使用独立配置文件后修改theme、shortcuts等配置时浏览器能即时反映变化。实战建议与注意事项始终使用defineConfig包裹配置获得完整类型推断的同时写法上也与官方示例、社区生态保持一致善用预设而非从零写规则presetWind3()等预设已覆盖绝大多数常用工具类自定义rules只补充差异部分可参考 Rules 配置用content精确控制提取范围大型项目应通过content.pipeline.include/exclude与content.filesystem显式声明扫描范围兼顾提取准确性与构建性能把共享数据放进configDeps主题令牌等外部文件变更即可触发热重载避免频繁重启多环境配置可在package.json脚本中为不同环境指定不同的configFile路径配合 Vite 的--config或插件的configFile参数或利用envMode: dev | build区分开发/构建行为完整的配置参考所有顶层选项的详细类型、默认值与子选项说明统一查阅 docs/config/index.md 及其子页面Rules、Shortcuts、Theme、Variants、Extractors、Preflights、Layers、Presets、Transformers、Processors、Autocomplete。小结uno.config.ts是 UnoCSS 项目中连接声明式配置与按需生成引擎的枢纽命名约定与configFile让各集成工具能自动或手动定位配置defineConfig提供类型安全loadConfig完成默认值、内联配置与文件配置的合并createRecoveryConfigLoader与 Vite 的ConfigHMRPlugin则保证了开发阶段的健壮与流畅。掌握这份配置的编写与加载原理就等于掌握了 UnoCSS 的全局控制台。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考