UnoCSS CLI 完全指南：用 @unocss/cli 在传统后端与命令行工作流中生成原子化 CSS

UnoCSS CLI 完全指南用 unocss/cli 在传统后端与命令行工作流中生成原子化 CSS【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocssunocss/cli是 UnoCSS 的命令行入口专为无法或不便于接入构建工具插件体系的传统后端场景设计只需给定一组 glob 扫描模式它就能从模板、脚本文件中提取类名、应用 transformers、并产出可直接部署的uno.css。本文以packages-engine/cli/README.md及其指向的官方文档 CLI 集成文档 为核心结合 CLI 源码实现 与 测试用例完整覆盖安装、全部命令行选项、配置文件中的cli.entry高级用法、--rewrite与--split-css的底层行为以及 watch 模式的工作机制。包定位与安装unocss/cli的包描述为 CLI for UnoCSS当前仓库中版本号为66.10.0见 package.json通过bin字段暴露unocss可执行命令bin/unocss.mjs。它独立于 Vite、PostCSS、Webpack 等集成方式核心价值在于从任意 glob 匹配的文件中扫描并提取 utilities内置--watch开发监听模式通过uno.config.ts支持完整自定义配置提供多个输出选项输出文件名、stdout、压缩、重写源文件、CSS 拆分等支持多个 entry pattern分别产出不同 CSS 文件。安装有两种方式。CLI 随unocss全量包一起分发pnpm add -D unocss # 或 yarn / npm / bun yarn add -D unocss npm install -D unocss bun add -D unocss也可以只安装独立的 CLI 包pnpm add -D unocss/cli yarn add -D unocss/cli npm install -D unocss/cli bun add -D unocss/cli注意官方文档特别提示如果你找不到unocss二进制例如使用pnpm且只安装了unocss包需要显式安装unocss/cli独立包。基本用法glob 模式与多入口CLI 接受一个或多个 glob 模式作为位置参数unocss site/snippets/**/*.php site/templates/**/*.php配合 npm scripts 的典型配置注意官方文档强调npm script 中的 glob 模式要加转义引号防止 shell 提前展开{ scripts: { dev: unocss \site/{snippets,templates}/**/*.php\ --watch, build: unocss \site/{snippets,templates}/**/*.php\ }, devDependencies: { unocss/cli: latest } }开发时用--watch或-w监听文件变化生产构建直接运行不带--watch的命令即可。默认情况下最终产物uno.css会生成在当前工作目录。如果既没有提供 glob 模式也没有在配置文件中定义cli.entryCLI 会抛出一个友好的PrettyError提示形如No glob patterns provided. Try unocss path/to/**/* or configure entries in uno.config file并将进程退出码置为 1见 resolveOptions 中的校验逻辑 与 errors.ts。选项解析细节所有命令行选项在 cli-start.ts 中基于cac注册默认值与文档表格一致--out-file默认解析为cwd/uno.css--preflights默认true默认开启 preflight 样式--split-css默认true--preset默认wind4--stdout模式下--watch与--out-file会被忽略且日志会重定向到 stderr保证 stdout 只有纯 CSS 输出有专门的测试keeps cli logs off stdout验证这一点见 cli.test.ts。配置文件uno.config.ts与cli.entry在项目根目录创建uno.config.js或uno.config.ts即可自定义 UnoCSS。除了 presets、theme、rules 等通用配置外详见 UnoCSS 配置文档CLI 提供了专属的cli配置块用于不同级别的文件打包与重写import { defineConfig } from unocss export default defineConfig({ cli: { entry: {}, // CliEntryItem | CliEntryItem[] }, // ... }) interface CliEntryItem { /** * Glob patterns to match files */ patterns: string[] /** * The output filename for the generated UnoCSS file */ outFile: string /** * Whether to rewrite the transformed utilities. * * - For css: if rewrite is true, it will not generate a new file, but directly modify the original file content. * - For other files: if rewrite is true, it replaces the original file with the transformed content. * * default false */ rewrite?: boolean /** * Whether to output CSS files scanned from patterns to outFile * * - false: Do not output CSS files * - true: Transform and output scanned CSS file contents to outFile * - multi: Output each CSS file separately with filename format ${originFile}-[hash] * - single: Merge multiple CSS files into one output file named outFile-merged.css * * default true */ splitCss?: boolean | multi | single }从 resolveOptions 源码 可以看到入口的合并规则命令行传入的patterns会被包装成第一个 entryoutFile取--out-file值默认cwd/uno.cssuno.config中cli.entry单个对象或数组经toArray归一化逐项追加每一项的rewrite/splitCss若未显式设置则回落到命令行--rewrite/--split-css的值两套 entry 共同构成options.entries构建时并行生成各自的输出文件。测试用例supports unocss.config.js cli options验证了多入口场景配置中声明views/index1.html → ./uno1.css、views/index2.html → ./test/uno2.css两条 entry构建后两个输出文件分别包含各自的.bg-blue与.bg-red规则见 cli.test.ts。Rewrite 源文件--rewrite--rewrite会让 CLI 把经过 transformers 变换后的内容写回源文件本身适合希望把 Variant Groups、Compile Class 等变换直接固化进代码的场景unocss src/**/*.vue --rewrite旧的--write-transformed选项已废弃源码中遇到它时仍会兼容处理但打印警告--write-transformed is deprecated, please use --rewrite instead见 resolveOptions 中的警告逻辑。transformers 的执行顺序在 transformFiles 中固定为pre → default → post三个阶段依次调用applyTransformers。测试applies pre, default, and post transformers精确验证了这一顺序三个自定义 transformer 分别向div/div前置div classbg-red、追加div classbg-blue与div classp-4最终文件内容为三段拼接的确定顺序且生成 CSS 中同时包含.bg-red、.bg-blue、.p-4。以 Variant Group 为例官方文档推荐搭配 transformers/variant-group 或 transformers/compile-class# 配置中启用 transformerVariantGroup() 后 unocss views/index.html --rewrite # div classborder-(~ solid red)/div → 被展开为 border-solid border-red 等标准类对应测试见 supports variantGroup transformer。CSS 拆分--split-css当扫描模式中混入了.css文件时--split-css控制这些 CSS 如何进入产物unocss src/**/*.vue --split-css true|false|multi|single取值行为false不输出 CSS 文件直接丢弃扫描到的.csstrue转换后的 CSS 内容并入outFilemulti每个 CSS 文件单独输出文件名为${originFile}-[hash].csssingle合并为outFile-merged.cssparseEntries 源码 清晰展示了这四种分支trueCSS 文件内容追加进outFile对应的缓存桶single全部 CSS 归入以outFile去掉.css后拼-merged.css命名的桶outFile.replace(/(\.css)?$/, -merged.css)multi为每个文件计算hash(file)输出${file}-${hash}.css当该 entry 只匹配到一个文件时退化为直接写入outFilefiles.length 1 ? currentOutFile : outFilefalseCSS 文件被静默丢弃。并入outFile的 CSS 在产物中带有/* Source: file */来源注释便于溯源CI 环境下不带注释见 generateSingle。默认 Preset--preset当项目中没有找到uno.config时可以用--preset指定 CLI 使用的默认 presetunocss src/**/*.vue --preset wind3|wind4wind4加载unocss/preset-wind4wind3加载unocss/preset-wind3。注意如果配置了uno.config该选项会被忽略。源码层面initializeConfig 在configSources为空时动态import对应 preset 包并同时挂入transformer-directives即默认支持apply指令然后ctx.uno.setConfig注入。这与 use default preset via cli option 测试--preset wind4下bg-blue与apply均生效相互印证。官方文档还有一条版本约束值得记住自v66.6.0起unocss/cli不再静默提供默认 preset——要么显式传--preset要么在配置文件中声明 presets。在wind3与wind4两代 preset 并存期间这一显式选择可以避免产物差异带来的困惑。完整命令行选项速查以下为 CLI 文档选项表 的完整内容并对照 cli-start.ts 中的注册代码 核实了默认值Options说明默认值-v, --version显示当前 UnoCSS 版本—-c, --config [file]指定配置文件路径自动探测-o, --out-file file生成的 UnoCSS 文件名cwd/uno.css--stdout将生成的 CSS 写入 STDOUT会忽略--watch与--out-filefalse-w, --watch监听 glob 匹配到的文件变化false--preflights是否输出 preflight 样式true--rewrite用变换后的 utilities 回写源文件false--write-transformed同--rewrite已废弃false-m, --minify压缩生成的 CSSfalse--debug启用调试模式打印文件生成明细表false--split-css [mode]控制扫描到的 CSS 文件的输出方式true/false/multi/singletrue--preset [default-preset]在无配置文件时切换wind3/wind4默认 presetwind4-h, --help显示可用 CLI 选项—补充两个源码中可见但文档未逐字展开的行为--stdout与--out-file互斥校验显式同时指定时直接logger.fatal报错退出--debug会调用 debugDetailsTable以表格形式打印每个输出文件与其来源文件的对应关系File Generation Details:排查多 entry 映射问题时非常有用。内部构建流程与 Watch 模式build 函数 串起完整管线initializeConfig→resolveOptions→parseEntriestinyglobby 扫描→ 非 watch 模式直接generatewatch 模式则先startWatcher再按需重建。Watch 模式要点实现见 watcher.ts底层使用chokidarusePolling: true、interval: 100轮询而非 inotify兼容性优先并忽略**/{.git,node_modules}/**监听范围包括所有已匹配的源文件以及配置文件本身ctx.getConfigFileList()触发事件后统一经 100ms 的perfect-debounce防抖再重新generate源文件change时只更新缓存中的代码内容unlink时从缓存移除add时重新parseEntries配置文件变化会触发ctx.reloadConfig()重新解析 options 与 entries 后再重建——测试supports uno.config.ts changed rebuild验证了修改uno.config.ts主题色后产物即时从red变为blue见 cli.test.ts。产物生成阶段generateSingle的关键步骤对每个源文件依次执行 pre/default/post transformers去除unocss-skip-start/unocss-skip-end之间的内容SKIP_COMMENT_RE这是官方测试unocss-skip uno.css覆盖的特性skip 块中的bg-red、text-white不会出现在产物里非 CSS 文件调用ctx.uno.generate(input, { preflights: false, minify: true, id })只收集matched token 集合不产出 CSS若rewrite开启将transformedCode写回原文件用 token 集合做最终一次generate此时才应用preflights与minify选项拼接扫描到的 CSS 内容后写入outFile目录不存在会自动mkdir -p。两阶段 generate 的设计意味着preflight 与最终压缩只执行一次与源文件数量无关。测试覆盖一览cli.test.ts 为上述行为提供了完整回归保障主要用例包括基本构建div classp-4 max-w-screen-md→ 快照断言uno.cssCSS 扫描 变换apply指令经transformer-directives展开--preset wind4默认 preset 行为unocss.config.jsshortcuts与cli.entry多输出文件--rewrite下 Variant Group、directives 的源文件回写pre/default/post transformer 顺序与错误传播transformer 抛错会中断构建含media的混合类型文件去重正确性unocss-skip注释块排除--stdout模式下 stdout 纯净性watch 模式下源文件变更与配置文件变更的重建Node 20 下跳过 watch 用例。小结unocss/cli把 UnoCSS 的核心能力压缩成一条命令glob 模式定义扫什么uno.config.ts的cli.entry定义输出到哪--rewrite让 transformers 直接改写源码--split-css精确控制伴随 CSS 的去向--preset决定无配置时的默认风味。对于 PHP、Laravel、Django 等传统后端模板项目或者任何不便引入前端构建工具的场景它提供了与 Vite/PostCSS 集成同等表达力的替代路径且 watch 模式下的文件级增量缓存与配置热重载使开发体验同样完整。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考