UnoCSS Rollup / Rolldown 插件详解在 Vite 之外按需生成 CSS 资源【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss本文围绕 UnoCSS 的 Rollup 集成文档 展开讲解如何在没有 Vite 的环境下通过unocss/rollup插件让 Rollup 或 Rolldown 构建管线接入 UnoCSS包括插件安装与接入方式、虚拟入口uno.css的引入时机、uno.config.ts与内联配置两种配置方式并结合仓库中插件的源码实现深入剖析其内容提取、虚拟模块解析与 CSS 资源产出emit asset的完整工作流。读完本文你可以独立搭建基于 Rollup/Rolldown 的 UnoCSS 构建链路并理解插件在每个构建生命周期钩子中实际做了哪些事。安装根据文档安装 UnoCSS 与打包器本身二者均为 dev 依赖# pnpm pnpm add -D unocss rollup# yarn yarn add -D unocss rollup# npm npm install -D unocss rollup# bun bun add -D unocss rollup如果你使用的是 Rolldown将命令中的rollup替换为rolldown即可。从插件包的 package.json 可以确认其适用前提rollup^4.0.0与rolldown^1.0.0都声明为可选的 peerDependencies即插件同时兼容两者但你的项目中至少需要安装其中一个插件实际发布的包名为unocss/rollup而文档中使用的unocss/rollup入口是由元包unocss的 exports 字段./rollup转发到unocss/rollup构建产物见 packages-presets/unocss/package.json。在 Rollup 中使用在rollup.config.ts中通过unocss/rollup导入插件并注册import UnoCSS from unocss/rollup export default { input: src/main.ts, plugins: [ UnoCSS(), ], }在 Rolldown 中使用Rolldown 的接入方式完全一致只是入口改为unocss/rolldownimport UnoCSS from unocss/rolldown export default { input: src/main.ts, plugins: [ UnoCSS(), ], }入口模块引入uno.css触发 CSS 产出在入口模块中显式导入虚拟 CSS 模块import uno.css插件在打包阶段会据此将生成的 CSS 作为输出资源asset发出产物文件名为uno.css你需要在部署或 HTML 构建流程中自行将该资源引入应用例如在 HTML 中link引入。这与 Vite 集成“运行时自动改写 CSS 导入”的行为不同是文档中强调的global模式语义插件不劫持你的 CSS 管线只负责把全量生成的 CSS 一次性 emit 出来。从源码 packages-integrations/rollup/src/index.ts 可以确认这一行为generateBundle钩子中只有当构建过程中确实出现过 UnoCSS 虚拟入口的导入内部vfsLayers非空时才会调用this.emitFile({ type: asset, name: uno.css, source: await generateCss() })产出资源generateCssindex.ts#L30-L39会先flushTasks等待所有提取任务完成再用ctx.uno.generate(tokens, { minify: true })生成压缩后的 CSS并按LAYER_IMPORTS顺序拼接各图层。配置方式独立配置文件创建uno.config.tsimport { defineConfig } from unocss export default defineConfig({ // ...UnoCSS options })配置文件中的 options 遵循 UnoCSS 标准的UserConfig结构presets、rules、variants、theme、content 等与 Vite 等集成共用同一套核心配置类型。直接向插件传入配置也可以不落地配置文件把配置对象作为参数传给插件import UnoCSS from unocss/rollup UnoCSS({ // ...UnoCSS options })这一点与实现一致插件工厂函数签名为RollupPlugin(configOrPath?: RollupPluginConfigTheme | string, defaults?: UserConfigDefaults)index.ts#L16-L23第一个参数既可以是配置对象也可以是自定义配置文件路径配置加载由共享层createContext中的createRecoveryConfigLoaderunocss/config完成未显式传参时会自动从process.cwd()向上查找默认的uno.config.ts。此外插件还通过process.env.NODE_ENV推断环境index.ts#L21development时以dev模式运行否则以build模式运行影响生成器的输出策略如 source map 相关行为。checkImport选项忘记写import uno.css时的告警插件配置类型 types.ts 在标准UserConfig之外额外定义了一个 Rollup 集成特有的选项export interface RollupPluginConfigTheme extends object object extends UserConfigTheme { /** * Warn when no UnoCSS virtual CSS entry is imported. * default false */ checkImport?: boolean }默认值为false。启用后UnoCSS({ checkImport: true })如果整个构建过程中没有任何模块导入过 UnoCSS 虚拟入口generateBundle会主动输出警告[unocss] Entry module not found. Did you add import uno.css in your main entry?index.ts#L99-L104。由于该模式下 CSS 完全靠 emit 产出漏写入口导入意味着产物中静默缺失全部 UnoCSS 样式这个选项正是针对这一故障模式的安全网。源码级原理插件在各生命周期钩子中的工作流Rollup 插件本体只有约 110 行packages-integrations/rollup/src/index.ts其完整调用链如下可作为理解 UnoCSS 各类集成共性的最小范本1.buildStart加载配置并启动全局内容提取buildStart 钩子 先await ctx.ready等待配置加载完成随后清空vfsLayers、tasks等状态并压入setupContentExtractor(ctx)任务。该函数定义在 virtual-shared/integration/src/content.ts它会处理两类配置化内容源content.inline内联文本/函数直接extract其中出现的原子类content.filesystem使用tinyglobby按 glob 匹配文件cwd为项目根逐文件读取、过 filter、应用 transformers 后提取 tokens读取按BATCH_SIZE 50并发分批执行content.ts#L62-L65。值得注意的是Rollup 插件调用setupContentExtractor时不传shouldWatch默认为false即不做文件监听——提取在每次构建时一次性完成这与 Rollup 一次性构建、无 dev server 的场景相符。2.transform逐模块提取与 transformer 应用每个通过filter的代码模块都会走 transform 钩子依次应用pre→ 默认 →post三类 transformers如transformer-directives、transformer-variant-group将转换后的代码交给extract(code, id)提取 tokens。filter的判定逻辑在 context.ts#L94-L98含unocss-ignore注释的模块跳过含unocss-include、unocss-placeholder的模块强制纳入其余走defaultPipelineInclude/Exclude的 glob 过滤可用content.pipeline配置覆盖content.pipeline: false可完全关闭文件提取。3.resolveId/load把uno.css映射为虚拟模块这是“global模式下必须显式import uno.css”背后的机制。resolveId 钩子 将导入 id 交给共享层 resolveId其匹配规则来自 constants.ts 中的 VIRTUAL_ENTRY_ALIASexport const VIRTUAL_ENTRY_ALIAS [ /^(?:virtual:)?uno(?::(.))?\.css(\?.*)?$/, ]可以确认以下导入形式都会被解析为 UnoCSS 虚拟入口import uno.css—— 全部图层import virtual:uno.css—— 带virtual:前缀的等价写法import uno:layer.css—— 只产出指定图层layer的 CSS。匹配成功后插件把 id 重写到形如/__uno.css的路径前缀由virtualModulePrefix决定默认__uno见 context.ts#L116-L132再在 Rollup 侧注册一个带\0前缀的纯虚拟模块 id\0unocss:layer同一 layer 被多个文件重复导入时只会保留首次出现并给出warn。load钩子对该虚拟模块返回code: index.ts#L84-L94因为 CSS 内容不走模块图而是最终统一走 emit。4.generateBundle一次性 emituno.css如前文所述generateBundle在vfsLayers非空时调用generateCss()并 emit 名为uno.css的 asset。由于提取与生成都发生在此阶段最终产出的 CSS 覆盖了所有被transform捕获的模块 content配置声明的内容源中出现过的全部 tokens这正是global模式的含义不依赖某个具体 CSS 模块在模块图中的位置而是全局收集、集中产出。适用前提与限制小结依赖前提rollup ^4.0.0或rolldown ^1.0.0二者至少装其一packages-integrations/rollup/package.json 中均为 optional peer必须显式import uno.css或uno:layer.css否则不会产出任何 CSS可用checkImport: true获得构建期告警该集成只做一次性 CSS 产出minified无 watch适合库构建、CLI 打包等离线场景需要 HMR、按模块注入 CSS 的场景应改用unocss/vite等集成插件导出的defineConfig只是原样返回配置对象index.ts#L12-L14类型约束来自RollupPluginConfig即UserConfigcheckImport。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
UnoCSS Rollup / Rolldown 插件详解：在 Vite 之外按需生成 CSS 资源
UnoCSS Rollup / Rolldown 插件详解在 Vite 之外按需生成 CSS 资源【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss本文围绕 UnoCSS 的 Rollup 集成文档 展开讲解如何在没有 Vite 的环境下通过unocss/rollup插件让 Rollup 或 Rolldown 构建管线接入 UnoCSS包括插件安装与接入方式、虚拟入口uno.css的引入时机、uno.config.ts与内联配置两种配置方式并结合仓库中插件的源码实现深入剖析其内容提取、虚拟模块解析与 CSS 资源产出emit asset的完整工作流。读完本文你可以独立搭建基于 Rollup/Rolldown 的 UnoCSS 构建链路并理解插件在每个构建生命周期钩子中实际做了哪些事。安装根据文档安装 UnoCSS 与打包器本身二者均为 dev 依赖# pnpm pnpm add -D unocss rollup# yarn yarn add -D unocss rollup# npm npm install -D unocss rollup# bun bun add -D unocss rollup如果你使用的是 Rolldown将命令中的rollup替换为rolldown即可。从插件包的 package.json 可以确认其适用前提rollup^4.0.0与rolldown^1.0.0都声明为可选的 peerDependencies即插件同时兼容两者但你的项目中至少需要安装其中一个插件实际发布的包名为unocss/rollup而文档中使用的unocss/rollup入口是由元包unocss的 exports 字段./rollup转发到unocss/rollup构建产物见 packages-presets/unocss/package.json。在 Rollup 中使用在rollup.config.ts中通过unocss/rollup导入插件并注册import UnoCSS from unocss/rollup export default { input: src/main.ts, plugins: [ UnoCSS(), ], }在 Rolldown 中使用Rolldown 的接入方式完全一致只是入口改为unocss/rolldownimport UnoCSS from unocss/rolldown export default { input: src/main.ts, plugins: [ UnoCSS(), ], }入口模块引入uno.css触发 CSS 产出在入口模块中显式导入虚拟 CSS 模块import uno.css插件在打包阶段会据此将生成的 CSS 作为输出资源asset发出产物文件名为uno.css你需要在部署或 HTML 构建流程中自行将该资源引入应用例如在 HTML 中link引入。这与 Vite 集成“运行时自动改写 CSS 导入”的行为不同是文档中强调的global模式语义插件不劫持你的 CSS 管线只负责把全量生成的 CSS 一次性 emit 出来。从源码 packages-integrations/rollup/src/index.ts 可以确认这一行为generateBundle钩子中只有当构建过程中确实出现过 UnoCSS 虚拟入口的导入内部vfsLayers非空时才会调用this.emitFile({ type: asset, name: uno.css, source: await generateCss() })产出资源generateCssindex.ts#L30-L39会先flushTasks等待所有提取任务完成再用ctx.uno.generate(tokens, { minify: true })生成压缩后的 CSS并按LAYER_IMPORTS顺序拼接各图层。配置方式独立配置文件创建uno.config.tsimport { defineConfig } from unocss export default defineConfig({ // ...UnoCSS options })配置文件中的 options 遵循 UnoCSS 标准的UserConfig结构presets、rules、variants、theme、content 等与 Vite 等集成共用同一套核心配置类型。直接向插件传入配置也可以不落地配置文件把配置对象作为参数传给插件import UnoCSS from unocss/rollup UnoCSS({ // ...UnoCSS options })这一点与实现一致插件工厂函数签名为RollupPlugin(configOrPath?: RollupPluginConfigTheme | string, defaults?: UserConfigDefaults)index.ts#L16-L23第一个参数既可以是配置对象也可以是自定义配置文件路径配置加载由共享层createContext中的createRecoveryConfigLoaderunocss/config完成未显式传参时会自动从process.cwd()向上查找默认的uno.config.ts。此外插件还通过process.env.NODE_ENV推断环境index.ts#L21development时以dev模式运行否则以build模式运行影响生成器的输出策略如 source map 相关行为。checkImport选项忘记写import uno.css时的告警插件配置类型 types.ts 在标准UserConfig之外额外定义了一个 Rollup 集成特有的选项export interface RollupPluginConfigTheme extends object object extends UserConfigTheme { /** * Warn when no UnoCSS virtual CSS entry is imported. * default false */ checkImport?: boolean }默认值为false。启用后UnoCSS({ checkImport: true })如果整个构建过程中没有任何模块导入过 UnoCSS 虚拟入口generateBundle会主动输出警告[unocss] Entry module not found. Did you add import uno.css in your main entry?index.ts#L99-L104。由于该模式下 CSS 完全靠 emit 产出漏写入口导入意味着产物中静默缺失全部 UnoCSS 样式这个选项正是针对这一故障模式的安全网。源码级原理插件在各生命周期钩子中的工作流Rollup 插件本体只有约 110 行packages-integrations/rollup/src/index.ts其完整调用链如下可作为理解 UnoCSS 各类集成共性的最小范本1.buildStart加载配置并启动全局内容提取buildStart 钩子 先await ctx.ready等待配置加载完成随后清空vfsLayers、tasks等状态并压入setupContentExtractor(ctx)任务。该函数定义在 virtual-shared/integration/src/content.ts它会处理两类配置化内容源content.inline内联文本/函数直接extract其中出现的原子类content.filesystem使用tinyglobby按 glob 匹配文件cwd为项目根逐文件读取、过 filter、应用 transformers 后提取 tokens读取按BATCH_SIZE 50并发分批执行content.ts#L62-L65。值得注意的是Rollup 插件调用setupContentExtractor时不传shouldWatch默认为false即不做文件监听——提取在每次构建时一次性完成这与 Rollup 一次性构建、无 dev server 的场景相符。2.transform逐模块提取与 transformer 应用每个通过filter的代码模块都会走 transform 钩子依次应用pre→ 默认 →post三类 transformers如transformer-directives、transformer-variant-group将转换后的代码交给extract(code, id)提取 tokens。filter的判定逻辑在 context.ts#L94-L98含unocss-ignore注释的模块跳过含unocss-include、unocss-placeholder的模块强制纳入其余走defaultPipelineInclude/Exclude的 glob 过滤可用content.pipeline配置覆盖content.pipeline: false可完全关闭文件提取。3.resolveId/load把uno.css映射为虚拟模块这是“global模式下必须显式import uno.css”背后的机制。resolveId 钩子 将导入 id 交给共享层 resolveId其匹配规则来自 constants.ts 中的 VIRTUAL_ENTRY_ALIASexport const VIRTUAL_ENTRY_ALIAS [ /^(?:virtual:)?uno(?::(.))?\.css(\?.*)?$/, ]可以确认以下导入形式都会被解析为 UnoCSS 虚拟入口import uno.css—— 全部图层import virtual:uno.css—— 带virtual:前缀的等价写法import uno:layer.css—— 只产出指定图层layer的 CSS。匹配成功后插件把 id 重写到形如/__uno.css的路径前缀由virtualModulePrefix决定默认__uno见 context.ts#L116-L132再在 Rollup 侧注册一个带\0前缀的纯虚拟模块 id\0unocss:layer同一 layer 被多个文件重复导入时只会保留首次出现并给出warn。load钩子对该虚拟模块返回code: index.ts#L84-L94因为 CSS 内容不走模块图而是最终统一走 emit。4.generateBundle一次性 emituno.css如前文所述generateBundle在vfsLayers非空时调用generateCss()并 emit 名为uno.css的 asset。由于提取与生成都发生在此阶段最终产出的 CSS 覆盖了所有被transform捕获的模块 content配置声明的内容源中出现过的全部 tokens这正是global模式的含义不依赖某个具体 CSS 模块在模块图中的位置而是全局收集、集中产出。适用前提与限制小结依赖前提rollup ^4.0.0或rolldown ^1.0.0二者至少装其一packages-integrations/rollup/package.json 中均为 optional peer必须显式import uno.css或uno:layer.css否则不会产出任何 CSS可用checkImport: true获得构建期告警该集成只做一次性 CSS 产出minified无 watch适合库构建、CLI 打包等离线场景需要 HMR、按模块注入 CSS 的场景应改用unocss/vite等集成插件导出的defineConfig只是原样返回配置对象index.ts#L12-L14类型约束来自RollupPluginConfig即UserConfigcheckImport。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考